feat(byRole): Add name option (testing-library#368)

* feat(byRole): Add `name` option * Recommend byRole more * resolve Kent's review * Try another query recommendation * Fix more by*

Author: eps1lon

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

@@ -187,8 +187,12 @@ cy.findByLabelText('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>
@@ -590,6 +594,7 @@ getByRole(
  options?: {
  exact?: boolean = true,
  hidden?: boolean = true,
+ name?: TextMatch,
  normalizer?: NormalizerFn,
  }): HTMLElement
 ```
@@ -604,6 +609,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