Skip to content

Commit 2eb9777

Browse files
docs: queryByRole new section for description option
1 parent 3187f77 commit 2eb9777

File tree

1 file changed

+34
-5
lines changed

1 file changed

+34
-5
lines changed

docs/queries/byrole.mdx

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -66,11 +66,7 @@ not replace the functionality of these attributes. For example
6666
`getByAltText('fancy image')` and `getByRole('img', { name: 'fancy image' })`.
6767
However, the image will not display its description if `fancy.jpg` could not be
6868
loaded. Whether you want to assert this functionality in your test or not is up
69-
to you.<br/> The accessible description is for cases where you have some
70-
elements which don't have a corresponding accessible name but they do have a
71-
description. For example, this can be the case for elements with
72-
[alertdialog](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) role, where
73-
the `aria-describedby` attribute is used to describe the elements content.
69+
to you.
7470

7571
## Options
7672

@@ -319,3 +315,36 @@ To learn more about the `aria-level` property, see
319315

320316
> The `level` option is _only_ applicable to the `heading` role. An error will
321317
> be thrown when used with any other role.
318+
319+
### `description`
320+
321+
You can filter the returned elements by their
322+
[accessible description](https://www.w3.org/TR/accname-1.1/#mapping_additional_nd_description)
323+
for those cases where you have several elements with the same role and they
324+
don't have an accessible name but they do have a description.<br /> This would
325+
be the case for elements with
326+
[alertdialog](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) role, where the
327+
`aria-describedby` attribute is used to describe the elements content.
328+
329+
For example in
330+
331+
```html
332+
<body>
333+
<ul>
334+
<li role="alertdialog" aria-describedby="notification-id-1">
335+
<div><button>Close</button></div>
336+
<div id="notification-id-1">You have unread emails</div>
337+
</li>
338+
<li role="alertdialog" aria-describedby="notification-id-2">
339+
<div><button>Close</button></div>
340+
<div id="notification-id-2">Your session is about to expire</div>
341+
</li>
342+
</ul>
343+
</body>
344+
```
345+
346+
You can query an specific element like this
347+
348+
```js
349+
getByrole('alertdialog', {description: 'Your session is about to expire'})
350+
```

0 commit comments

Comments
 (0)