From ea1f9b16317f67bb79f99b36602e49355602aec8 Mon Sep 17 00:00:00 2001
From: Sebastian Silbermann <silbermann.sebastian@gmail.com>
Date: Sat, 25 Jan 2020 18:25:28 +0100
Subject: [PATCH 1/5] feat(byRole): Add `name` option

---
 docs/dom-testing-library/api-queries.md | 27 +++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/dom-testing-library/api-queries.md b/docs/dom-testing-library/api-queries.md
index 7b9ff55b5..35fa5c240 100644
--- a/docs/dom-testing-library/api-queries.md
+++ b/docs/dom-testing-library/api-queries.md
@@ -164,8 +164,9 @@ 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. 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>
@@ -178,6 +179,9 @@ const inputNode = getByLabelText(container, 'Username', {
 })
 ```
 
+Otherwise `byRole('textbox', { name: 'Username' })` works as well and is robust
+against switching to `aria-label` or `aria-labelledby`.
+
 ### `ByPlaceholderText`
 
 > getByPlaceholderText, queryByPlaceholderText, getAllByPlaceholderText,
@@ -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 `byRole(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 `byRole('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

From f3759ec46f0d61b7176e8e93cc4d137c84e0c641 Mon Sep 17 00:00:00 2001
From: Sebastian Silbermann <silbermann.sebastian@gmail.com>
Date: Sat, 25 Jan 2020 18:26:21 +0100
Subject: [PATCH 2/5] Recommend byRole more

---
 docs/guide-which-query.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/guide-which-query.md b/docs/guide-which-query.md
index bcca97343..30c1fb14b 100644
--- a/docs/guide-which-query.md
+++ b/docs/guide-which-query.md
@@ -14,6 +14,11 @@ possible. With this in mind, we recommend this order of priority:
    1. `getByLabelText`: Only really good for form fields, but this is the number
       one method a user finds those elements, so it should be your top
       preference.
+   1. `getByRole`: With the `name` option you can basically query the full
+      accessibility tree. It can query all the elements you can query with the
+      other accessility query. But consider that you still might want to assert
+      if an element has an actual `<label>` element or a `placeholder`
+      attribute.
    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.
@@ -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

From 7143d960061357aae80c3b88e08a0e03bd9e772e Mon Sep 17 00:00:00 2001
From: Sebastian Silbermann <silbermann.sebastian@gmail.com>
Date: Sat, 1 Feb 2020 21:49:46 +0100
Subject: [PATCH 3/5] resolve Kent's review

---
 docs/dom-testing-library/api-queries.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/dom-testing-library/api-queries.md b/docs/dom-testing-library/api-queries.md
index 35fa5c240..f40c3aa1b 100644
--- a/docs/dom-testing-library/api-queries.md
+++ b/docs/dom-testing-library/api-queries.md
@@ -164,8 +164,11 @@ cy.getByLabelText('username').should('exist')
 
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-It will NOT find the input node for label text broken up by elements. If it is
-important that you query an actual `<label>` element you can provide a
+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
@@ -179,9 +182,6 @@ const inputNode = getByLabelText(container, 'Username', {
 })
 ```
 
-Otherwise `byRole('textbox', { name: 'Username' })` works as well and is robust
-against switching to `aria-label` or `aria-labelledby`.
-
 ### `ByPlaceholderText`
 
 > getByPlaceholderText, queryByPlaceholderText, getAllByPlaceholderText,
@@ -594,12 +594,12 @@ 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 `byRole(expectedRole, { name: 'The name' })`. The
+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 `byRole('image', { name: 'fancy image' })`.
+`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.

From 448d6d3e0a6202d9f5058e7d22691fca6c08b1bc Mon Sep 17 00:00:00 2001
From: Sebastian Silbermann <silbermann.sebastian@gmail.com>
Date: Tue, 4 Feb 2020 18:34:36 +0100
Subject: [PATCH 4/5] Try another query recommendation

---
 docs/guide-which-query.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/guide-which-query.md b/docs/guide-which-query.md
index 30c1fb14b..30312a604 100644
--- a/docs/guide-which-query.md
+++ b/docs/guide-which-query.md
@@ -14,17 +14,17 @@ possible. With this in mind, we recommend this order of priority:
    1. `getByLabelText`: Only really good for form fields, but this is the number
       one method a user finds those elements, so it should be your top
       preference.
-   1. `getByRole`: With the `name` option you can basically query the full
-      accessibility tree. It can query all the elements you can query with the
-      other accessility query. But consider that you still might want to assert
-      if an element has an actual `<label>` element or a `placeholder`
-      attribute.
    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

From 310551605ed136d4d60c85774ba40a425b151b90 Mon Sep 17 00:00:00 2001
From: Sebastian Silbermann <silbermann.sebastian@gmail.com>
Date: Tue, 4 Feb 2020 18:35:55 +0100
Subject: [PATCH 5/5] Fix more by*

---
 docs/dom-testing-library/api-queries.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/dom-testing-library/api-queries.md b/docs/dom-testing-library/api-queries.md
index f40c3aa1b..51f602db3 100644
--- a/docs/dom-testing-library/api-queries.md
+++ b/docs/dom-testing-library/api-queries.md
@@ -595,8 +595,8 @@ 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
+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' })`.