feat(queries): Add docs about byRole#hidden (#266)

eps1lon · alexkrolick · commit 96b436f26a4f · 2019-09-24T11:20:28.000-07:00
* feat(queries): Add docs about byRole#hidden

* Add example for hidden
diff --git a/docs/dom-testing-library/api-queries.md b/docs/dom-testing-library/api-queries.md
@@ -533,6 +533,7 @@ getByRole(
   role: TextMatch,
   options?: {
     exact?: boolean = true,
+    hidden?: boolean = false,
     normalizer?: NormalizerFn,
   }): HTMLElement
 ```
@@ -544,6 +545,27 @@ attribute. The
 [W3C HTML recommendation](https://www.w3.org/TR/html5/index.html#contents) lists
 all HTML elements with their default aria roles.
 
+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
+`role="none"` and `role="presentation"` which are considered in the query in any
+case. For example in
+
+```html
+<body>
+  <main aria-hidden="true">
+    <button>Open dialog</button>
+  </main>
+  <div role="dialog">
+    <button>Close dialog</button>
+  </div>
+</body>
+```
+
+`getByRole('button')` would only return the `Close dialog`-button. To make
+assertions about the `Open dialog`-button you would need to use
+`getAllByRole('button', { hidden: true })`.
+
 ```html
 <div role="dialog">...</div>
 ```
