feat(byRole): Add name option

docs/dom-testing-library/api-queries.md

@@ -164,8 +164,12 @@ cy.getByLabelText('username').should('exist')
 
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-It will NOT find the input node for label text broken up by elements. For this
-case, you can provide a `selector` in the options:
+It will NOT find the input node for label text broken up by elements. You can
+use `getByRole('textbox', { name: 'Username' })` instead which is robust against
+switching to `aria-label` or `aria-labelledby`.
+
+If it is important that you query an actual `<label>` element you can provide a
+`selector` in the options:
 
 ```html
 <label> <span>Username</span> <input /> </label>
@@ -567,6 +571,7 @@ getByRole(
   options?: {
     exact?: boolean = true,
     hidden?: boolean = true,
+    name?: TextMatch,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -581,6 +586,24 @@ Library uses `aria-query` under the hood to find those elements by their default
 ARIA roles, you can find in their docs
 [which HTML Elements with inherent roles are mapped to each role](https://github.com/A11yance/aria-query#elements-to-roles).
 
+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
+["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
+accessible name query does not replace other queries such as `*ByAlt` or
+`*ByTitle`. While the accessible name can be equal to these attributes, it does
+not replace the functionality of these attributes. For example
+`<img aria-label="fancy image" src="fancy.jpg" />` will be returned for both
+`getByAlt('fancy image')` and `getByRole('image', { name: 'fancy image' })`.
+However, the image will not display its description if `fancy.jpg` could not be
+loaded. Whether you want assert this functionality in your test or not is up to
+you.
+
 If you set `hidden` to `true` elements that are normally excluded from the
 accessibility tree are considered for the query as well. The default behavior
 follows https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion with the exception of

docs/guide-which-query.md

@@ -17,9 +17,14 @@ possible. With this in mind, we recommend this order of priority:
    1. `getByPlaceholderText`:
       [A placeholder is not a substitute for a label](https://www.nngroup.com/articles/form-design-placeholders/).
       But if that's all you have, then it's better than alternatives.
+   1. `getByRole`: This can be used to query every element that is exposed in
+      the
+      [accessibility tree](https://developer.mozilla.org/en-US/docs/Glossary/AOM).
+      With the `name` option you can filter the returned elements by their
+      [accessible name](https://www.w3.org/TR/accname-1.1/). This should be your
+      top preference for interactive elements such as buttons.
    1. `getByText`: Not useful for forms, but this is the number 1 method a user
-      finds other elements (like buttons to click), so it should be your top
-      preference for non-form elements.
+      finds most non-interactive elements (listitems or divs).
    1. `getByDisplayValue`: The current value of a form element can be useful
       when navigating a page with filled-in values.
 1. **Semantic Queries** HTML5 and ARIA compliant selectors. Note that the user
@@ -29,8 +34,6 @@ possible. With this in mind, we recommend this order of priority:
       `area`, and `input`), then you can use this to find that element.
    1. `getByTitle`: The title attribute is not consistently read by
       screenreaders, and is not visible by default for sighted users
-   1. `getByRole`: This can be used to select dialog boxes and other
-      difficult-to-capture elements in a more semantic way
 1. **Test IDs**
    1. `getByTestId`: The user cannot see (or hear) these, so this is only
       recommended for cases where you can't match by role or text or it doesn't