Skip to content

docs: queryByRole new description option #1035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 5, 2022
Merged

docs: queryByRole new description option #1035

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3187f77
docs: queryByRole new description option
CarlosCortizasCT Apr 4, 2022
2eb9777
docs: queryByRole new section for description option
CarlosCortizasCT Apr 5, 2022
9da0a15
docs: queryByRole spell check corrections
CarlosCortizasCT Apr 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions docs/queries/byrole.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ getByRole(
exact?: boolean = true,
hidden?: boolean = false,
name?: TextMatch,
description?: TextMatch,
normalizer?: NormalizerFn,
selected?: boolean,
checked?: boolean,
Expand Down Expand Up @@ -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
Expand All @@ -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.<br/> 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

Expand Down