docs: reorganize query docs

- give queries a top-level nav entry instead of nesting under DOM Testing Library - give each query its own page - reorganize pages like "Which Query" under the new heading - update internal links and redirects
testing-library · Jan 13, 2021 · dcf41db · dcf41db
1 parent 1055c11
commit dcf41db
Show file tree

Hide file tree

Showing 34 changed files with 8,286 additions and 1,325 deletions.
diff --git a/docs/contributing.mdx b/docs/contributing.mdx
@@ -40,35 +40,6 @@ Links:
 
 <!-- prettier-ignore-start -->
 
-[npm]: https://www.npmjs.com/
-[node]: https://nodejs.org
-[build-badge]: https://img.shields.io/travis/kentcdodds/react-testing-library.svg?style=flat-square
-[build]: https://travis-ci.org/kentcdodds/react-testing-library
-[coverage-badge]: https://img.shields.io/codecov/c/github/kentcdodds/react-testing-library.svg?style=flat-square
-[coverage]: https://codecov.io/github/kentcdodds/react-testing-library
-[version-badge]: https://img.shields.io/npm/v/react-testing-library.svg?style=flat-square
-[package]: https://www.npmjs.com/package/react-testing-library
-[downloads-badge]: https://img.shields.io/npm/dm/react-testing-library.svg?style=flat-square
-[npmtrends]: http://www.npmtrends.com/react-testing-library
-[license-badge]: https://img.shields.io/npm/l/react-testing-library.svg?style=flat-square
-[license]: https://github.com/testing-library/react-testing-library/blob/master/LICENSE
-[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
-[prs]: http://makeapullrequest.com
-[donate-badge]: https://img.shields.io/badge/$-support-green.svg?style=flat-square
-[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
-[coc]: https://github.com/testing-library/react-testing-library/blob/master/CODE_OF_CONDUCT.md
-[github-watch-badge]: https://img.shields.io/github/watchers/kentcdodds/react-testing-library.svg?style=social
-[github-watch]: https://github.com/testing-library/react-testing-library/watchers
-[github-star-badge]: https://img.shields.io/github/stars/kentcdodds/react-testing-library.svg?style=social
-[github-star]: https://github.com/testing-library/react-testing-library/stargazers
-[twitter]: https://twitter.com/intent/tweet?text=Check%20out%20react-testing-library%20by%20%40kentcdodds%20https%3A%2F%2Fgithub.com%2Fkentcdodds%2Freact-testing-library%20%F0%9F%91%8D
-[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/testing-library/react-testing-library.svg?style=social
-[emojis]: https://github.com/kentcdodds/all-contributors#emoji-key
-[all-contributors]: https://github.com/kentcdodds/all-contributors
-[set-immediate]: https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate
-[guiding-principle]: https://twitter.com/kentcdodds/status/977018512689455106
-[data-testid-blog-post]: https://blog.kentcdodds.com/making-your-ui-tests-resilient-to-change-d37a6ee37269
-[dom-testing-lib-textmatch]: https://github.com/testing-library/dom-testing-library#textmatch
 [bugs]: https://github.com/testing-library/react-testing-library/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc
 [requests]: https://github.com/testing-library/react-testing-library/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen
 [good-first-issue]: https://github.com/testing-library/react-testing-library/issues?utf8=✓&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A"good+first+issue"+

diff --git a/docs/dom-testing-library/api-async.mdx b/docs/dom-testing-library/api-async.mdx
@@ -1,13 +1,33 @@
 ---
 id: api-async
-title: Async Utilities
+title: Async Methods
 ---
 
 Several utilities are provided for dealing with asynchronous code. These can be
-useful to wait for an element to appear or disappear in response to an action.
-(See the [guide to testing disappearance](guide-disappearance.mdx).)
+useful to wait for an element to appear or disappear in response to an event,
+user action, timeout, or Promise. (See the
+[guide to testing disappearance](guide-disappearance.mdx).)
 
-All the async utils are built on top of `waitFor`.
+The async methods return Promises, so be sure to use `await` or `.then` when
+calling them.
+
+## `findBy` Queries
+
+`findBy` methods are a combination of `getBy`
+[queries](queries/about.mdx#types-of-queries) and [`waitFor`](#waitfor). They
+accept the waitFor options as the last argument (i.e.
+`await screen.findByText('text', queryOptions, waitForOptions)`).
+
+`findBy` queries work when you expect an element to appear but the change to the
+DOM might not happen immediately.
+
+```js
+const button = screen.getByRole('button', { name: 'Click Me' })
+fireEvent.click(button)
+await screen.findByText('Clicked once')
+fireEvent.click(button)
+await screen.findByText('Clicked twice')
+```
 
 ## `waitFor`
 
@@ -122,7 +142,20 @@ waitForElementToBeRemoved(() => getByText(/not here/i)).catch((err) =>
 
 The options object is forwarded to `waitFor`.
 
-## `wait` (DEPRECATED, use waitFor instead)
+## Deprecated Methods
+
+`wait`, `waitForDomChange`, and `waitForElement` have been combined into the
+`waitFor` method
+
+<details>
+
+<br />
+
+<summary>Deprecated Methods</summary>
+
+### `wait`
+
+> (DEPRECATED, use waitFor instead)
 
 ```typescript
 function wait<T>(
@@ -144,7 +177,9 @@ Unlike wait, the callback parameter is mandatory in waitFor. Although you can
 migrate an existing `wait()` call to `waitFor( () => {} )`, it is considered bad
 practice to use an empty callback because it will make the tests more fragile.
 
-## `waitForDomChange` (DEPRECATED, use waitFor instead)
+### `waitForDomChange`
+
+> (DEPRECATED, use waitFor instead)
 
 ```typescript
 function waitForDomChange<T>(options?: {
@@ -205,7 +240,9 @@ will detect additions and removals of child elements (including text nodes) in
 the `container` and any of its descendants. It will also detect attribute
 changes.
 
-## `waitForElement` (DEPRECATED, use `find*` queries or `waitFor`)
+### `waitForElement`
+
+> (DEPRECATED, use `find*` queries or `waitFor`)
 
 ```typescript
 function waitForElement<T>(
@@ -263,3 +300,5 @@ The default `mutationObserverOptions` is
 will detect additions and removals of child elements (including text nodes) in
 the `container` and any of its descendants. It will also detect attribute
 changes.
+
+</details>
diff --git a/docs/dom-testing-library/api-configuration.mdx b/docs/dom-testing-library/api-configuration.mdx
@@ -61,31 +61,35 @@ configure({ testIdAttribute: 'data-my-test-id' })
 ## Configuration options:
 
 ### `computedStyleSupportsPseudoElements`
-Set to `true` if `window.getComputedStyle` supports pseudo-elements i.e. a second argument. If
-you're using testing-library in a browser you almost always want to set this to
-`true`. Only very old browser don't support this property (such as IE 8 and
-earlier). However, `jsdom` does not support the second argument currently. This
-includes versions of `jsdom` prior to `16.4.0` and any version that logs a
-`not implemented` warning when calling `getComputedStyle` with a second argument
-e.g. `window.getComputedStyle(document.createElement('div'), '::after')`.
-Defaults to `false`
+
+Set to `true` if `window.getComputedStyle` supports pseudo-elements i.e. a
+second argument. If you're using testing-library in a browser you almost always
+want to set this to `true`. Only very old browser don't support this property
+(such as IE 8 and earlier). However, `jsdom` does not support the second
+argument currently. This includes versions of `jsdom` prior to `16.4.0` and any
+version that logs a `not implemented` warning when calling `getComputedStyle`
+with a second argument e.g.
+`window.getComputedStyle(document.createElement('div'), '::after')`. Defaults to
+`false`
 
 ### `defaultHidden`
+
 The default value for the `hidden` option used by
 [`getByRole`](api-queries.mdx#byrole). Defaults to `false`.
 
 ### `showOriginalStackTrace`
-By default, `waitFor` will ensure that the stack trace
-for errors thrown by Testing Library is cleaned up and shortened so it's easier
-for you to identify the part of your code that resulted in the error (async
-stack traces are hard to debug). If you want to disable this, then
-set`showOriginalStackTrace` to `false`. You can also disable this for a specific
-call in the options you pass to `waitFor`.
+
+By default, `waitFor` will ensure that the stack trace for errors thrown by
+Testing Library is cleaned up and shortened so it's easier for you to identify
+the part of your code that resulted in the error (async stack traces are hard to
+debug). If you want to disable this, then set`showOriginalStackTrace` to
+`false`. You can also disable this for a specific call in the options you pass
+to `waitFor`.
 
 ### `throwSuggestions` (experimental)
-When enabled, if [better queries](https://testing-library.com/docs/guide-which-query) are
-available the test will fail and provide a suggested query to use instead.
-Default to `false`.
+
+When enabled, if [better queries](queries/about.mdx#priority) are available the
+test will fail and provide a suggested query to use instead. Default to `false`.
 
 To disable a suggestion for a single query just add `{suggest:false}` as an
 option.
@@ -95,14 +99,17 @@ screen.getByTestId('foo', { suggest: false }) // will not throw a suggestion
 ```
 
 ### `testIdAttribute`
-The attribute used by [`getByTestId`](api-queries.mdx#bytestid) and related queries. Defaults to
-`data-testid`.
+
+The attribute used by [`getByTestId`](api-queries.mdx#bytestid) and related
+queries. Defaults to `data-testid`.
 
 ### `getElementError`
-A function that returns the error used when
-[`getBy*`](api-queries.mdx#getby) or [`getAllBy*`](api-queries.mdx#getallby)
-fail. Takes the error message and container object as arguments.
+
+A function that returns the error used when [`getBy*`](api-queries.mdx#getby) or
+[`getAllBy*`](api-queries.mdx#getallby) fail. Takes the error message and
+container object as arguments.
 
 ### `asyncUtilTimeout`
-The global timeout value in milliseconds used by `waitFor`
-utilities. Defaults to 1000ms.
+
+The global timeout value in milliseconds used by `waitFor` utilities. Defaults
+to 1000ms.
diff --git a/docs/dom-testing-library/api-helpers.mdx b/docs/dom-testing-library/api-helpers.mdx
@@ -140,8 +140,8 @@ could do:
 ```js
 import { within } from '@testing-library/dom'
 
-const { getByText } = within(document.getElementById('messages'))
-const helloMessage = getByText('hello')
+const messages = document.getElementById('messages')
+const helloMessage = within(messages).getByText('hello')
 ```
 
   </TabItem>
@@ -167,7 +167,9 @@ cy.get('form').within(() => {
   </TabItem>
   </Tabs>
 
-## `getRoles`
+## Accessibility
+
+### `getRoles`
 
 This function allows iteration over the implicit ARIA roles represented in a
 given tree of DOM nodes.
@@ -197,7 +199,7 @@ console.log(getRoles(nav))
 // }
 ```
 
-## `isInaccessible`
+### `isInaccessible`
 
 This function will compute if the given element should be excluded from the
 accessibility API by the browser. It implements every **MUST** criteria from the