diff --git a/docs/contributing.mdx b/docs/contributing.mdx
index 65791f758..619c6149c 100644
--- a/docs/contributing.mdx
+++ b/docs/contributing.mdx
@@ -40,35 +40,6 @@ Links:
-[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-accessibility.mdx b/docs/dom-testing-library/api-accessibility.mdx
new file mode 100644
index 000000000..d861c95ad
--- /dev/null
+++ b/docs/dom-testing-library/api-accessibility.mdx
@@ -0,0 +1,92 @@
+---
+id: api-accessibility
+title: Accessibility
+---
+
+## Testing for Accessibility
+
+One of the guiding principles of the Testing Library APIs is that they should
+enable you to test your app the way your users use it, including through
+accessibility interfaces like screen readers.
+
+See the page on [queries](queries/about.mdx#priority) for details on how using a
+semantic HTML query can make sure your app works with browser accessibility
+APIs.
+
+## `getRoles`
+
+This function allows iteration over the implicit ARIA roles represented in a
+given tree of DOM nodes.
+
+It returns an object, indexed by role name, with each value being an array of
+elements which have that implicit ARIA role.
+
+See
+[ARIA in HTML](https://www.w3.org/TR/html-aria/#document-conformance-requirements-for-use-of-aria-attributes-in-html)
+for more information about implicit ARIA roles.
+
+```javascript
+import { getRoles } from '@testing-library/dom'
+
+const nav = document.createElement('nav')
+nav.innerHTML = `
+
],
+// listitem: [, ]
+// }
+```
+
+## `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
+[Excluding Elements from the Accessibility Tree](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion)
+section in WAI-ARIA 1.2 with the exception of checking the `role` attribute.
+
+It is defined as:
+
+```typescript
+function isInaccessible(element: Element): boolean
+```
+
+## `logRoles`
+
+This helper function can be used to print out a list of all the implicit ARIA
+roles within a tree of DOM nodes, each role containing a list of all of the
+nodes which match that role. This can be helpful for finding ways to query the
+DOM under test with [getByRole](queries/byrole.mdx)
+
+```javascript
+import { logRoles } from '@testing-library/dom'
+
+const nav = document.createElement('nav')
+nav.innerHTML = `
+
+--------------------------------------------------
+listitem:
+
+
+--------------------------------------------------
+```
diff --git a/docs/dom-testing-library/api-async.mdx b/docs/dom-testing-library/api-async.mdx
index 71be357a1..d9eafdabc 100644
--- 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 (e.g.
+`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.
+
+
+
+
+
+Deprecated Methods
+
+### `wait`
+
+> (DEPRECATED, use waitFor instead)
```typescript
function wait(
@@ -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(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(
@@ -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.
+
+
diff --git a/docs/dom-testing-library/api-configuration.mdx b/docs/dom-testing-library/api-configuration.mdx
index 57d02abb4..7d772dff2 100644
--- a/docs/dom-testing-library/api-configuration.mdx
+++ b/docs/dom-testing-library/api-configuration.mdx
@@ -1,6 +1,6 @@
---
id: api-configuration
-title: Configuration
+title: Configuration Options
---
import Tabs from '@theme/Tabs'
@@ -16,7 +16,10 @@ The library can be configured via the `configure` function, which accepts:
return a plain JS object which will be merged as above, e.g.
`configure(existingConfig => ({something: [...existingConfig.something, 'extra value for the something array']}))`
-## Setup
+> **Note**
+>
+> Framework-specific wrappers like React Testing Library may add more options to
+> the ones shown below.
@@ -58,34 +61,38 @@ configure({ testIdAttribute: 'data-my-test-id' })
-## Configuration options:
+## 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`.
+[`getByRole`](queries/byrole.mdx). 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 +102,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`](queries/bytestid.mdx) 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.
+[get or find queries](queries/about.mdx#types-of-queries) 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-custom-queries.mdx b/docs/dom-testing-library/api-custom-queries.mdx
new file mode 100644
index 000000000..4b2b2d272
--- /dev/null
+++ b/docs/dom-testing-library/api-custom-queries.mdx
@@ -0,0 +1,121 @@
+---
+id: api-custom-queries
+title: Custom Queries
+---
+
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+## Custom Queries
+
+`DOM Testing Library` exposes many of the helper functions that are used to
+implement the default queries. You can use the helpers to build custom queries.
+For example, the code below shows a way to override the default `testId` queries
+to use a different data-attribute. (Note: test files would import
+`test-utils.js` instead of using `DOM Testing Library` directly).
+
+> **Note**
+>
+> Custom queries can be added to `React Testing Library`'s `render` method by
+> adding `queries` to the options config object. See the render
+> [options](react-testing-library/api.mdx#render-options).
+
+> Custom queries are different than
+> [custom render](react-testing-library/setup.mdx#custom-render) methods.
+
+```js
+// test-utils.js
+const domTestingLib = require('@testing-library/dom')
+const { queryHelpers } = domTestingLib
+
+export const queryByTestId = queryHelpers.queryByAttribute.bind(
+ null,
+ 'data-test-id'
+)
+export const queryAllByTestId = queryHelpers.queryAllByAttribute.bind(
+ null,
+ 'data-test-id'
+)
+
+export function getAllByTestId(container, id, ...rest) {
+ const els = queryAllByTestId(container, id, ...rest)
+ if (!els.length) {
+ throw queryHelpers.getElementError(
+ `Unable to find an element by: [data-test-id="${id}"]`,
+ container
+ )
+ }
+ return els
+}
+
+export function getByTestId(...args) {
+ const result = getAllByTestId(...args)
+ if (result.length > 0) {
+ return result[0]
+ }
+ return null
+}
+
+// re-export with overrides
+module.exports = {
+ ...domTestingLib,
+ getByTestId,
+ getAllByTestId,
+ queryByTestId,
+ queryAllByTestId,
+}
+```
+
+## `buildQueries`
+
+The `buildQueries` helper allows you to create custom queries with all standard
+[variants](api-queries.mdx) of queries in testing-library.
+
+See the [Add custom queries](react-testing-library/setup.mdx#add-custom-queries)
+section of the custom render guide for example usage.
+
+### Using other assertion libraries
+
+If you're not using jest, you may be able to find a similar set of custom
+assertions for your library of choice. Here's a list of alternatives to jest-dom
+for other popular assertion libraries:
+
+- [chai-dom](https://github.com/nathanboktae/chai-dom)
+
+If you're aware of some other alternatives, please
+[make a pull request](https://github.com/testing-library/testing-library-docs/pulls)
+and add it here!
+
+## `getNodeText`
+
+```typescript
+getNodeText(node: HTMLElement)
+```
+
+Returns the complete text content of an HTML element, removing any extra
+whitespace. The intention is to treat text in nodes exactly as how it is
+perceived by users in a browser, where any extra whitespace within words in the
+html code is not meaningful when the text is rendered.
+
+```javascript
+//
+// Hello
+// World !
+//
+const text = getNodeText(container.querySelector('div')) // "Hello World !"
+```
+
+This function is also used internally when querying nodes by their text content.
+This enables functions like `getByText` and `queryByText` to work as expected,
+finding elements in the DOM similarly to how users would do.
+
+The function has a special behavior for some input elements:
+
+```javascript
+//
+//
+const submitText = getNodeText(container.querySelector('input[type=submit]')) // "Send data"
+const buttonText = getNodeText(container.querySelector('input[type=button]')) // "Push me"
+
+These elements use the attribute `value` and display its value to the user.
+```
diff --git a/docs/dom-testing-library/api-debugging.mdx b/docs/dom-testing-library/api-debugging.mdx
new file mode 100644
index 000000000..020856a33
--- /dev/null
+++ b/docs/dom-testing-library/api-debugging.mdx
@@ -0,0 +1,114 @@
+---
+id: api-debugging
+title: Debugging
+---
+
+## Automatic Logging
+
+When you use any `get` calls in your test cases, the current state of the
+`container` (DOM) gets printed on the console. For example:
+
+```javascript
+//
Hello world
+getByText(container, 'Goodbye world') // will fail by throwing error
+```
+
+The above test case will fail, however it prints the state of your DOM under
+test, so you will get to see:
+
+```
+Unable to find an element with the text: Goodbye world. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible.
+Here is the state of your container:
+
+
+ Hello world
+
+
+```
+
+Note: Since the DOM size can get really large, you can set the limit of DOM
+content to be printed via environment variable `DEBUG_PRINT_LIMIT`. The default
+value is `7000`. You will see `...` in the console, when the DOM content is
+stripped off, because of the length you have set or due to default size limit.
+Here's how you might increase this limit when running tests:
+
+```
+DEBUG_PRINT_LIMIT=10000 npm test
+```
+
+This works on macOS/Linux, you'll need to do something else for Windows. If
+you'd like a solution that works for both, see
+[`cross-env`](https://www.npmjs.com/package/cross-env)
+
+## `prettyDOM`
+
+Built on top of
+[`pretty-format`](https://github.com/facebook/jest/tree/master/packages/pretty-format),
+this helper function can be used to print out readable representation of the DOM
+tree of a node. This can be helpful for instance when debugging tests.
+
+It is defined as:
+
+```typescript
+function prettyDOM(
+ node: HTMLElement,
+ maxLength?: number,
+ options?: Options
+): string
+```
+
+It receives the root node to print out, an optional extra parameter to limit the
+size of the resulting string, for cases when it becomes too large. It has a last
+parameter which allows you to configure your formatting as defined in the
+[options](https://github.com/facebook/jest/tree/master/packages/pretty-format#usage-with-options)
+of `pretty-format`.
+
+This function is usually used alongside `console.log` to temporarily print out
+DOM trees during tests for debugging purposes:
+
+```javascript
+const div = document.createElement('div')
+div.innerHTML = '
Hello World
'
+console.log(prettyDOM(div))
+//
+//
Hello World
+//
+```
+
+This function is what also powers
+[the automatic debugging output described above](#debugging).
+
+## `logRoles`
+
+This helper function can be used to print out a list of all the implicit ARIA
+roles within a tree of DOM nodes, each role containing a list of all of the
+nodes which match that role. This can be helpful for finding ways to query the
+DOM under test with [getByRole](queries/byrole.mdx)
+
+```javascript
+import { logRoles } from '@testing-library/dom'
+
+const nav = document.createElement('nav')
+nav.innerHTML = `
+
+--------------------------------------------------
+listitem:
+
+
+--------------------------------------------------
+```
diff --git a/docs/dom-testing-library/api-events.mdx b/docs/dom-testing-library/api-events.mdx
index cbd2a96fa..9bc3910bf 100644
--- a/docs/dom-testing-library/api-events.mdx
+++ b/docs/dom-testing-library/api-events.mdx
@@ -6,9 +6,11 @@ title: Firing Events
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
+> **Note**
+>
> Most projects have a few use cases for `fireEvent`, but the majority of the
> time you should probably use
-> [`@testing-library/user-event`](https://github.com/testing-library/user-event).
+> [`@testing-library/user-event`](ecosystem-user-event.mdx).
## `fireEvent`
diff --git a/docs/dom-testing-library/api-helpers.mdx b/docs/dom-testing-library/api-helpers.mdx
deleted file mode 100644
index c749d1c3e..000000000
--- a/docs/dom-testing-library/api-helpers.mdx
+++ /dev/null
@@ -1,327 +0,0 @@
----
-id: api-helpers
-title: Helpers
----
-
-import Tabs from '@theme/Tabs'
-import TabItem from '@theme/TabItem'
-
-## Custom Queries
-
-`DOM Testing Library` exposes many of the helper functions that are used to
-implement the default queries. You can use the helpers to build custom queries.
-For example, the code below shows a way to override the default `testId` queries
-to use a different data-attribute. (Note: test files would import
-`test-utils.js` instead of using `DOM Testing Library` directly).
-
-```js
-// test-utils.js
-const domTestingLib = require('@testing-library/dom')
-const { queryHelpers } = domTestingLib
-
-export const queryByTestId = queryHelpers.queryByAttribute.bind(
- null,
- 'data-test-id'
-)
-export const queryAllByTestId = queryHelpers.queryAllByAttribute.bind(
- null,
- 'data-test-id'
-)
-
-export function getAllByTestId(container, id, ...rest) {
- const els = queryAllByTestId(container, id, ...rest)
- if (!els.length) {
- throw queryHelpers.getElementError(
- `Unable to find an element by: [data-test-id="${id}"]`,
- container
- )
- }
- return els
-}
-
-export function getByTestId(...args) {
- const result = getAllByTestId(...args)
- if (result.length > 0) {
- return result[0]
- }
- return null
-}
-
-// re-export with overrides
-module.exports = {
- ...domTestingLib,
- getByTestId,
- getAllByTestId,
- queryByTestId,
- queryAllByTestId,
-}
-```
-
-> **Note**
->
-> Custom queries can be added to `React Testing Library`'s `render` method by
-> adding `queries` to the options config object. See the render
-> [options](react-testing-library/api.mdx#render-options).
-
-## `buildQueries`
-
-The `buildQueries` helper allows you to create custom queries with all standard
-[variants](api-queries.mdx) of queries in testing-library.
-
-See the [Add custom queries](react-testing-library/setup.mdx#add-custom-queries)
-section of the custom render guide for example usage.
-
-### Using other assertion libraries
-
-If you're not using jest, you may be able to find a similar set of custom
-assertions for your library of choice. Here's a list of alternatives to jest-dom
-for other popular assertion libraries:
-
-- [chai-dom](https://github.com/nathanboktae/chai-dom)
-
-If you're aware of some other alternatives, please
-[make a pull request](https://github.com/testing-library/testing-library-docs/pulls)
-and add it here!
-
-## `getNodeText`
-
-```typescript
-getNodeText(node: HTMLElement)
-```
-
-Returns the complete text content of an HTML element, removing any extra
-whitespace. The intention is to treat text in nodes exactly as how it is
-perceived by users in a browser, where any extra whitespace within words in the
-html code is not meaningful when the text is rendered.
-
-```javascript
-//
-// Hello
-// World !
-//
-const text = getNodeText(container.querySelector('div')) // "Hello World !"
-```
-
-This function is also used internally when querying nodes by their text content.
-This enables functions like `getByText` and `queryByText` to work as expected,
-finding elements in the DOM similarly to how users would do.
-
-The function has a special behavior for some input elements:
-
-```javascript
-//
-//
-const submitText = getNodeText(container.querySelector('input[type=submit]')) // "Send data"
-const buttonText = getNodeText(container.querySelector('input[type=button]')) // "Push me"
-
-These elements use the attribute `value` and display its value to the user.
-```
-
-## `within` and `getQueriesForElement` APIs
-
-`within` (an alias to `getQueriesForElement`) takes a DOM element and binds it
-to the raw query functions, allowing them to be used without specifying a
-container. It is the recommended approach for libraries built on this API and is
-in use in `React Testing Library` and `Vue Testing Library`.
-
-Example: To get the text 'hello' only within a section called 'messages', you
-could do:
-
-
-
-
-```js
-import { within } from '@testing-library/dom'
-
-const { getByText } = within(document.getElementById('messages'))
-const helloMessage = getByText('hello')
-```
-
-
-
-
-```jsx
-import { render, within } from '@testing-library/react'
-
-const { getByLabelText } = render()
-const signinModal = getByLabelText('Sign In')
-within(signinModal).getByPlaceholderText('Username')
-```
-
-
-
-
-```js
-cy.get('form').within(() => {
- cy.findByText('Button Text').should('be.disabled')
-})
-```
-
-
-
-
-## `getRoles`
-
-This function allows iteration over the implicit ARIA roles represented in a
-given tree of DOM nodes.
-
-It returns an object, indexed by role name, with each value being an array of
-elements which have that implicit ARIA role.
-
-See
-[ARIA in HTML](https://www.w3.org/TR/html-aria/#document-conformance-requirements-for-use-of-aria-attributes-in-html)
-for more information about implicit ARIA roles.
-
-```javascript
-import { getRoles } from '@testing-library/dom'
-
-const nav = document.createElement('nav')
-nav.innerHTML = `
-
],
-// listitem: [, ]
-// }
-```
-
-## `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
-[Excluding Elements from the Accessibility Tree](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion)
-section in WAI-ARIA 1.2 with the exception of checking the `role` attribute.
-
-It is defined as:
-
-```typescript
-function isInaccessible(element: Element): boolean
-```
-
-## Debugging
-
-When you use any `get` calls in your test cases, the current state of the
-`container` (DOM) gets printed on the console. For example:
-
-```javascript
-//
Hello world
-getByText(container, 'Goodbye world') // will fail by throwing error
-```
-
-The above test case will fail, however it prints the state of your DOM under
-test, so you will get to see:
-
-```
-Unable to find an element with the text: Goodbye world. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible.
-Here is the state of your container:
-
-
- Hello world
-
-
-```
-
-Note: Since the DOM size can get really large, you can set the limit of DOM
-content to be printed via environment variable `DEBUG_PRINT_LIMIT`. The default
-value is `7000`. You will see `...` in the console, when the DOM content is
-stripped off, because of the length you have set or due to default size limit.
-Here's how you might increase this limit when running tests:
-
-```
-DEBUG_PRINT_LIMIT=10000 npm test
-```
-
-This works on macOS/Linux, you'll need to do something else for Windows. If
-you'd like a solution that works for both, see
-[`cross-env`](https://www.npmjs.com/package/cross-env)
-
-### `prettyDOM`
-
-Built on top of
-[`pretty-format`](https://github.com/facebook/jest/tree/master/packages/pretty-format),
-this helper function can be used to print out readable representation of the DOM
-tree of a node. This can be helpful for instance when debugging tests.
-
-It is defined as:
-
-```typescript
-function prettyDOM(
- node: HTMLElement,
- maxLength?: number,
- options?: Options
-): string
-```
-
-It receives the root node to print out, an optional extra parameter to limit the
-size of the resulting string, for cases when it becomes too large. It has a last
-parameter which allows you to configure your formatting as defined in the
-[options](https://github.com/facebook/jest/tree/master/packages/pretty-format#usage-with-options)
-of `pretty-format`.
-
-This function is usually used alongside `console.log` to temporarily print out
-DOM trees during tests for debugging purposes:
-
-```javascript
-const div = document.createElement('div')
-div.innerHTML = '
Hello World
'
-console.log(prettyDOM(div))
-//
-//
Hello World
-//
-```
-
-This function is what also powers
-[the automatic debugging output described above](#debugging).
-
-### `logRoles`
-
-This helper function can be used to print out a list of all the implicit ARIA
-roles within a tree of DOM nodes, each role containing a list of all of the
-nodes which match that role. This can be helpful for finding ways to query the
-DOM under test with [getByRole](api-queries.mdx#byrole)
-
-```javascript
-import { logRoles } from '@testing-library/dom'
-
-const nav = document.createElement('nav')
-nav.innerHTML = `
-
-//
-//
-// --------------------------------------------------
-// listitem:
-//
-//
-//
-//
-//
-//
-// --------------------------------------------------
-```
diff --git a/docs/dom-testing-library/api-queries.mdx b/docs/dom-testing-library/api-queries.mdx
deleted file mode 100644
index f718ccdd3..000000000
--- a/docs/dom-testing-library/api-queries.mdx
+++ /dev/null
@@ -1,1116 +0,0 @@
----
-id: api-queries
-title: Queries
----
-
-import Tabs from '@theme/Tabs'
-import TabItem from '@theme/TabItem'
-
-## Variants
-
-> `getBy` queries are shown by default in the [query documentation](#queries)
-> below.
-
-### getBy
-
-`getBy*` queries return the matching node for a query, and throw an error if no
-elements match or if more than one match is found (use `getAllBy` instead).
-
-### getAllBy
-
-`getAllBy*` queries return an array of all matching nodes for a query, and throw
-an error if no elements match.
-
-### queryBy
-
-`queryBy*` queries return the first matching node for a query, and return `null`
-if no elements match. This is useful for asserting an element that is not
-present. This throws an error if more than one match is found (use `queryAllBy`
-instead).
-
-### queryAllBy
-
-`queryAllBy*` queries return an array of all matching nodes for a query, and
-return an empty array (`[]`) if no elements match.
-
-### findBy
-
-`findBy*` queries return a promise which resolves when an element is found which
-matches the given query. The promise is rejected if no element is found or if
-more than one element is found after a default timeout of `1000`ms. If you need
-to find more than one element, then use `findAllBy`.
-
-> **Note**
->
-> this is a simple combination of `getBy*` queries and
-> [`waitFor`](api-async.mdx#waitfor). The `findBy*` queries accept the `waitFor`
-> options as the last argument. (i.e.
-> `screen.findByText('text', queryOptions, waitForOptions)`)
-
-### findAllBy
-
-`findAllBy*` queries return a promise which resolves to an array of elements
-when any elements are found which match the given query. The promise is rejected
-if no elements are found after a default timeout of `1000`ms.
-
-## Options
-
-The argument to a query can be a _string_, _regular expression_, or _function_.
-There are also options to adjust how node text is parsed.
-
-See [TextMatch](#textmatch) for documentation on what can be passed to a query.
-
-## `screen`
-
-All of the queries exported by DOM Testing Library accept a `container` as the
-first argument. Because querying the entire `document.body` is very common, DOM
-Testing Library also exports a `screen` object which has every query that is
-pre-bound to `document.body` (using the
-[`within`](/docs/dom-testing-library/api-helpers#within-and-getqueriesforelement-apis)
-functionality).
-
-Here's how you use it:
-
-```javascript
-import { screen } from '@testing-library/dom'
-// NOTE: many framework-implementations of Testing Library
-// re-export everything from `@testing-library/dom` so you
-// may be able to import screen from your framework-implementation:
-// import {render, screen} from '@testing-library/react'
-
-const exampleHTML = `
-
-
-`
-document.body.innerHTML = exampleHTML
-const exampleInput = screen.getByLabelText(/example/i)
-```
-
-> **Note**
->
-> You need a global DOM environment to use `screen`. If you're using jest, with
-> the
-> [testEnvironment](https://jestjs.io/docs/en/configuration#testenvironment-string)
-> set to `jsdom`, a global DOM environment will be available for you.
->
-> If you're loading your test with a `script` tag, make sure it comes after the
-> `body`. An example can be seen
-> [here](https://github.com/testing-library/dom-testing-library/issues/700#issuecomment-692218886).
-
-### `screen.debug`
-
-For convenience screen also exposes a `debug` method in addition to the queries.
-This method is essentially a shortcut for `console.log(prettyDOM())`. It
-supports debugging the document, a single element, or an array of elements.
-
-```javascript
-import { screen } from '@testing-library/dom'
-
-document.body.innerHTML = `
-
- multi-test
-
multi-test
-`
-
-// debug document
-screen.debug()
-// debug single element
-screen.debug(screen.getByText('test'))
-// debug multiple elements
-screen.debug(screen.getAllByText('multi-test'))
-```
-
-### `screen.logTestingPlaygroundURL`
-
-For debugging using [testing-playground](https://testing-playground.com), screen
-exposes this convenient method which logs a URL that can be opened in a browser.
-
-```javascript
-import { screen } from '@testing-library/dom'
-
-document.body.innerHTML = `
-
- multi-test
-
multi-test
-`
-
-// log entire document to testing-playground
-screen.logTestingPlaygroundURL()
-// log a single element
-screen.logTestingPlaygroundURL(screen.getByText('test'))
-```
-
-## Queries
-
-> **Note**
->
-> These queries are the base queries and require you to pass a `container` as
-> the first argument. Most framework-implementations of Testing Library provide
-> a pre-bound version of these queries when you render your components with them
-> which means you do not have to provide a container. In addition, if you just
-> want to query `document.body` then you can use the [`screen`](#screen) export
-> as demonstrated above (using `screen` is recommended).
-
-### `ByLabelText`
-
-> getByLabelText, queryByLabelText, getAllByLabelText, queryAllByLabelText,
-> findByLabelText, findAllByLabelText
-
-```typescript
-getByLabelText(
- container: HTMLElement, // if you're using `screen`, then skip this argument
- text: TextMatch,
- options?: {
- selector?: string = '*',
- exact?: boolean = true,
- normalizer?: NormalizerFn,
- }): HTMLElement
-```
-
-This will search for the label that matches the given [`TextMatch`](#textmatch),
-then find the element associated with that label.
-
-The example below will find the input node for the following DOM structures:
-
-```js
-// for/htmlFor relationship between label and form element id
-
-
-
-// The aria-labelledby attribute with form elements
-
-
-
-// Wrapper labels
-
-
-// Wrapper labels where the label text is in another child element
-
-
-// aria-label attributes
-// Take care because this is not a label that users can see on the page,
-// so the purpose of your input must be obvious to visual users.
-
-```
-
-
-
-
-```js
-import { screen } from '@testing-library/dom'
-
-const inputNode = screen.getByLabelText('Username')
-```
-
-
-
-
-```jsx
-import { render, screen } from '@testing-library/react'
-
-render()
-
-const inputNode = screen.getByLabelText('username')
-```
-
-
-
-
-```js
-cy.findByLabelText('username').should('exist')
-```
-
-
-
-
-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 `