@@ -20,6 +20,7 @@ getByRole(
20
20
exact?: boolean = true ,
21
21
hidden?: boolean = false ,
22
22
name?: TextMatch ,
23
+ description?: TextMatch ,
23
24
normalizer?: NormalizerFn ,
24
25
selected?: boolean ,
25
26
checked?: boolean ,
@@ -50,11 +51,11 @@ because the `button` element has default characteristics that conflict with the
50
51
> will not include elements with a subclass role like ` switch ` .
51
52
52
53
You can query the returned element(s) by their
53
- [ accessible name] ( https://www.w3.org/TR/accname-1.1/ ) . The accessible name is
54
- for simple cases equal to e.g. the label of a form element, or the text content
55
- of a button, or the value of the ` aria-label ` attribute. It can be used to query
56
- a specific element if multiple elements with the same role are present on the
57
- rendered content. For an in-depth guide check out
54
+ [ accessible name or description ] ( https://www.w3.org/TR/accname-1.1/ ) . The
55
+ accessible name is for simple cases equal to e.g. the label of a form element,
56
+ or the text content of a button, or the value of the ` aria-label ` attribute. It
57
+ can be used to query a specific element if multiple elements with the same role
58
+ are present on the rendered content. For an in-depth guide check out
58
59
[ "What is an accessible name?" from ThePacielloGroup] ( https://developer.paciellogroup.com/blog/2017/04/what-is-an-accessible-name/ ) .
59
60
If you only query for a single element with ` getByText('The name') ` it's
60
61
oftentimes better to use ` getByRole(expectedRole, { name: 'The name' }) ` . The
@@ -314,3 +315,36 @@ To learn more about the `aria-level` property, see
314
315
315
316
> The ` level ` option is _ only_ applicable to the ` heading ` role. An error will
316
317
> 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 element's 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 a specific element like this
347
+
348
+ ``` js
349
+ getByrole (' alertdialog' , {description: ' Your session is about to expire' })
350
+ ```
0 commit comments