From 3187f77983d4bfb7dac939c6014abe41c7c341e7 Mon Sep 17 00:00:00 2001 From: Carlos Martinez Date: Mon, 4 Apr 2022 15:07:18 +0200 Subject: [PATCH 1/3] docs: queryByRole new description option --- docs/queries/byrole.mdx | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/queries/byrole.mdx b/docs/queries/byrole.mdx index cbfaa17c1..0fe8f3cb2 100644 --- a/docs/queries/byrole.mdx +++ b/docs/queries/byrole.mdx @@ -20,6 +20,7 @@ getByRole( exact?: boolean = true, hidden?: boolean = false, name?: TextMatch, + description?: TextMatch, normalizer?: NormalizerFn, selected?: boolean, checked?: boolean, @@ -50,11 +51,11 @@ because the `button` element has default characteristics that conflict with the > will not include elements with a subclass role like `switch`. You can query the returned element(s) by their -[accessible name](https://www.w3.org/TR/accname-1.1/). The accessible name is -for simple cases equal to e.g. the label of a form element, or the text content -of a button, or the value of the `aria-label` attribute. It can be used to query -a specific element if multiple elements with the same role are present on the -rendered content. For an in-depth guide check out +[accessible name or description](https://www.w3.org/TR/accname-1.1/). The +accessible name is for simple cases equal to e.g. the label of a form element, +or the text content of a button, or the value of the `aria-label` attribute. It +can be used to query a specific element if multiple elements with the same role +are present on the rendered content. For an in-depth guide check out ["What is an accessible name?" from ThePacielloGroup](https://developer.paciellogroup.com/blog/2017/04/what-is-an-accessible-name/). If you only query for a single element with `getByText('The name')` it's oftentimes better to use `getByRole(expectedRole, { name: 'The name' })`. The @@ -65,7 +66,11 @@ not replace the functionality of these attributes. For example `getByAltText('fancy image')` and `getByRole('img', { name: 'fancy image' })`. However, the image will not display its description if `fancy.jpg` could not be loaded. Whether you want to assert this functionality in your test or not is up -to you. +to you.
The accessible description is for cases where you have some +elements which don't have a corresponding accessible name but they do have a +description. For example, this can be the case for elements with +[alertdialog](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) role, where +the `aria-describedby` attribute is used to describe the elements content. ## Options From 2eb9777e53c6e8ca35e997e5cd022e2e0f747531 Mon Sep 17 00:00:00 2001 From: Carlos Martinez Date: Tue, 5 Apr 2022 08:51:46 +0200 Subject: [PATCH 2/3] docs: queryByRole new section for description option --- docs/queries/byrole.mdx | 39 ++++++++++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 5 deletions(-) diff --git a/docs/queries/byrole.mdx b/docs/queries/byrole.mdx index 0fe8f3cb2..bfcf84e73 100644 --- a/docs/queries/byrole.mdx +++ b/docs/queries/byrole.mdx @@ -66,11 +66,7 @@ not replace the functionality of these attributes. For example `getByAltText('fancy image')` and `getByRole('img', { name: 'fancy image' })`. However, the image will not display its description if `fancy.jpg` could not be loaded. Whether you want to assert this functionality in your test or not is up -to you.
The accessible description is for cases where you have some -elements which don't have a corresponding accessible name but they do have a -description. For example, this can be the case for elements with -[alertdialog](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) role, where -the `aria-describedby` attribute is used to describe the elements content. +to you. ## Options @@ -319,3 +315,36 @@ To learn more about the `aria-level` property, see > The `level` option is _only_ applicable to the `heading` role. An error will > be thrown when used with any other role. + +### `description` + +You can filter the returned elements by their +[accessible description](https://www.w3.org/TR/accname-1.1/#mapping_additional_nd_description) +for those cases where you have several elements with the same role and they +don't have an accessible name but they do have a description.
This would +be the case for elements with +[alertdialog](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) role, where the +`aria-describedby` attribute is used to describe the elements content. + +For example in + +```html + + + +``` + +You can query an specific element like this + +```js +getByrole('alertdialog', {description: 'Your session is about to expire'}) +``` From 9da0a1598132cb4c75ffa91d03ab9f16f24a9784 Mon Sep 17 00:00:00 2001 From: Carlos Martinez Date: Tue, 5 Apr 2022 13:18:12 +0200 Subject: [PATCH 3/3] docs: queryByRole spell check corrections --- docs/queries/byrole.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/queries/byrole.mdx b/docs/queries/byrole.mdx index bfcf84e73..f2070dbc8 100644 --- a/docs/queries/byrole.mdx +++ b/docs/queries/byrole.mdx @@ -324,7 +324,7 @@ for those cases where you have several elements with the same role and they don't have an accessible name but they do have a description.
This would be the case for elements with [alertdialog](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) role, where the -`aria-describedby` attribute is used to describe the elements content. +`aria-describedby` attribute is used to describe the element's content. For example in @@ -343,7 +343,7 @@ For example in ``` -You can query an specific element like this +You can query a specific element like this ```js getByrole('alertdialog', {description: 'Your session is about to expire'})