Skip to content

Add docs for ByRole 'level' option #582

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 2 commits into from
Aug 27, 2020
Merged

Add docs for ByRole 'level' option #582

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bfd125d
Add docs for ByRole 'level' option
winterlamon Aug 27, 2020
52452cf
Add missing angle bracket in example
winterlamon Aug 27, 2020
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
52 changes: 51 additions & 1 deletion docs/dom-testing-library/api-queries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -625,6 +625,7 @@ getByRole(
checked?: boolean,
pressed?: boolean,
queryFallbacks?: boolean,
level?: number,
}): HTMLElement
```

Expand All @@ -635,7 +636,7 @@ attribute. Here you can see
[a table of HTML elements with their default and desired roles](https://www.w3.org/TR/html-aria/#docconformance).

Please note that setting a `role` and/or `aria-*` attribute that matches the
implicit ARIA semantics is unnecessary and is **not recomended** as these
implicit ARIA semantics is unnecessary and is **not recommended** as these
properties are already set by the browser, and we must not use the `role` and
`aria-*` attributes in a manner that conflicts with the semantics described. For
example, a `button` element can't have the `role` attribute of `heading`,
Expand Down Expand Up @@ -787,6 +788,8 @@ cy.findByRole('dialog').should('exist')

<!--END_DOCUSAURUS_CODE_TABS-->

#### `queryFallbacks`

By default, it's assumed that the first role of each element is supported, so
only the first role can be queried. If you need to query an element by any of
its fallback roles instead, you can use `queryFallbacks: true`.
Expand All @@ -803,6 +806,53 @@ roles and therefore match the same element.
> roles get introduced and you want to start supporting those as well as older
> environments that don't understand that role (yet).

#### `level`

An element with the `heading` role can be queried by any heading level
`getByRole('heading')` or by a specific heading level using the `level` option
`getByRole('heading', { level: 2 })`.

The `level` option queries the element(s) with the `heading` role matching the
indicated level determined by the semantic HTML heading elements `<h1>-<h6>` or
matching the `aria-level` attribute.

Given the example below,

```html
<body>
<section>
<h1>Heading Level One</h1>
<h2>First Heading Level Two</h2>
<h3>Heading Level Three</h3>
<div role="heading" aria-level="2">Second Heading Level Two</div>
</section>
</body>
```

you can query the `Heading Level Three` heading using
`getByRole('heading', { level: 3 })`.

```js
getByRole('heading', { level: 1 })
// <h1>Heading Level One</h1>

getAllByRole('heading', { level: 2 })
// [
// <h2>First Heading Level Two</h2>,
// <div role="heading" aria-level="2">Second Heading Level Two</div>
// ]
```

While it is possible to explicitly set `role="heading"` and `aria-level`
attribute on an element, it is **strongly encouraged** to use the semantic HTML
headings `<h1>-<h6>`.

To learn more about the `aria-level` property, see
[ARIA `aria-level`](https://www.w3.org/TR/wai-aria-1.2/#aria-level).

> The `level` option is _only_ applicable to the `heading` role. An error will
> be thrown when used with any other role.

### `ByTestId`

> getByTestId, queryByTestId, getAllByTestId, queryAllByTestId, findByTestId,
Expand Down