diff --git a/docs/dom-testing-library/api-queries.md b/docs/dom-testing-library/api-queries.md index aeae82341..1843cd285 100644 --- a/docs/dom-testing-library/api-queries.md +++ b/docs/dom-testing-library/api-queries.md @@ -625,6 +625,7 @@ getByRole( checked?: boolean, pressed?: boolean, queryFallbacks?: boolean, + level?: number, }): HTMLElement ``` @@ -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`, @@ -787,6 +788,8 @@ cy.findByRole('dialog').should('exist') +#### `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`. @@ -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 `

-

` or +matching the `aria-level` attribute. + +Given the example below, + +```html + +
+

Heading Level One

+

First Heading Level Two

+

Heading Level Three

+
Second Heading Level Two
+
+ +``` + +you can query the `Heading Level Three` heading using +`getByRole('heading', { level: 3 })`. + +```js +getByRole('heading', { level: 1 }) +//

Heading Level One

+ +getAllByRole('heading', { level: 2 }) +// [ +//

First Heading Level Two

, +//
Second Heading Level Two
+// ] +``` + +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 `

-

`. + +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,