+
+
+
+Can I write unit tests with this library?
+ +Definitely yes! You can write unit and integration tests with this library. See +below for more on how to mock dependencies (because this library intentionally +does NOT support shallow rendering) if you want to unit test a high level +component. The tests in this project show several examples of unit testing with +this library. + +As you write your tests, keep in mind: + +> The more your tests resemble the way your software is used, the more +> confidence they can give you. - [17 Feb 2018][guiding-principle] + +
+
+
+
++ If I can't use shallow rendering, how do I mock out components in tests? +
+ +In general, you should avoid mocking out components (see +[the Guiding Principles section](guiding-principles.mdx)). However, if you need +to, then try to use [ng-mocks](https://ng-mocks.sudo.eu/) and its +[`MockBuilder`](https://ng-mocks.sudo.eu/extra/with-3rd-party#testing-libraryangular-and-mockbuilder). + +```typescript +import {Component, NgModule} from '@angular/core' +import {render, screen} from '@testing-library/angular' +import {MockBuilder} from 'ng-mocks' + +@Component({ + selector: 'app-parent-component', + template: 'Child component
', +}) +class ChildComponent {} + +@NgModule({ + declarations: [ParentComponent, ChildComponent], +}) +export class AppModule {} + +describe('ParentComponent', () => { + it('should not render ChildComponent when shallow rendering', async () => { + // all imports, declarations and exports of AppModule will be mocked. + const dependencies = MockBuilder(ParentComponent, AppModule).build() + + await render(ParentComponent, dependencies) + + expect(screen.queryByText('Child component')).toBeNull() + }) +}) +``` + +
+
+
+
+
+
+
+
+[guiding-principle]: https://twitter.com/kentcdodds/status/977018512689455106
+
+
diff --git a/docs/angular-testing-library/intro.md b/docs/angular-testing-library/intro.md
deleted file mode 100644
index 830975b59..000000000
--- a/docs/angular-testing-library/intro.md
+++ /dev/null
@@ -1,87 +0,0 @@
----
-id: intro
-title: Angular Testing Library
----
-
-🦔 [`@testing-library/angular`][gh] Simple and complete
-[Angular](https://angular.io) testing utilities that encourage good testing
-practices.
-
-```bash
-npm install --save-dev @testing-library/angular
-```
-
-- [`@testing-library/angular-testing-library` on GitHub][gh]
-
-## Usage
-
-counter.component.ts
-
-```typescript
-@Component({
- selector: 'counter',
- template: `
-
- Current Count: {{ counter }}
-
- `,
-})
-export class CounterComponent {
- @Input() counter = 0
-
- increment() {
- this.counter += 1
- }
-
- decrement() {
- this.counter -= 1
- }
-}
-```
-
-counter.component.spec.ts
-
-```typescript
-import { render } from '@testing-library/angular'
-import CounterComponent from './counter.component.ts'
-
-describe('Counter', () => {
- test('should render counter', async () => {
- const { getByText } = await render(CounterComponent, {
- componentProperties: { counter: 5 },
- })
-
- expect(getByText('Current Count: 5'))
- })
-
- test('should increment the counter on click', async () => {
- const { getByText, click } = await render(CounterComponent, {
- componentProperties: { counter: 5 },
- })
-
- click(getByText('+'))
-
- expect(getByText('Current Count: 6'))
- })
-})
-```
-
-## API
-
-There is a small difference between `@testing-library/angular` and the
-`testing-library` family, in this library we also expose all of the events via
-the `render` function. This is done to trigger Angular's change detection after
-each interaction.
-
-You can also import these event via `@testing-library/angular`, but the
-Angular's change detection will not be triggered automatically.
-
-The same counts for all the queries provided by the DOM Testing Library
-(`@testing-library/dom`), these are also re-exported and can be imported via
-`@testing-library/angular`.
-
-```typescript
-import { getByText, click } from '@testing-library/angular'
-```
-
-[gh]: https://github.com/testing-library/angular-testing-library
diff --git a/docs/angular-testing-library/intro.mdx b/docs/angular-testing-library/intro.mdx
new file mode 100644
index 000000000..a7820b7f0
--- /dev/null
+++ b/docs/angular-testing-library/intro.mdx
@@ -0,0 +1,65 @@
+---
+id: intro
+title: Angular Testing Library
+sidebar_label: Introduction
+---
+
+[`Angular Testing Library`](https://github.com/testing-library/angular-testing-library)
+builds on top of
+[`DOM Testing Library`](https://github.com/testing-library/dom-testing-library)
+by adding APIs for working with Angular components.
+Starting from ATL version 17, you also need to install `@testing-library/dom`:
+
+```bash npm2yarn
+npm install --save-dev @testing-library/angular @testing-library/dom
+```
+
+Or, you can use the `ng add` command.
+This sets up your project to use Angular Testing Library, which also includes the installation of `@testing-library/dom`.
+
+```bash
+ng add @testing-library/angular
+```
+
+- [`@testing-library/angular-testing-library` on GitHub](https://github.com/testing-library/angular-testing-library)
+
+## The problem
+
+You want to write maintainable tests for your Angular components. As a part of
+this goal, you want your tests to avoid including implementation details of your
+components and rather focus on making your tests give you the confidence for
+which they are intended. As part of this, you want your testbase to be
+maintainable in the long run so refactors of your components (changes to
+implementation but not functionality) don't break your tests and slow you and
+your team down.
+
+## This solution
+
+The `Angular Testing Library` is a very lightweight solution for testing Angular
+components. It provides light utility functions on top of
+[`DOM Testing Library`](https://github.com/testing-library/dom-testing-library)
+in a way that encourages better testing practices. Its primary guiding principle
+is:
+
+> [The more your tests resemble the way your software is used, the more confidence they can give you.](guiding-principles.mdx)
+
+So rather than dealing with instances of rendered Angular components, your tests
+will work with actual DOM nodes. The utilities this library provides facilitate
+querying the DOM in the same way the user would. Finding form elements by their
+label text (just like a user would), finding links and buttons from their text
+(like a user would). It also exposes a recommended way to find elements by a
+`data-testid` as an "escape hatch" for elements where the text content and label
+do not make sense or is not practical.
+
+This library encourages your applications to be more accessible and allows you
+to get your tests closer to using your components the way a user will, which
+allows your tests to give you more confidence that your application will work
+when a real user uses it.
+
+The `Angular Testing Library`:
+
+- Re-exports the `query` and `fireEvent` utility functions from
+ [`DOM Testing Library`](https://github.com/testing-library/dom-testing-library).
+- Encapsulates the `fireEvent` functions of your component to automatically call
+ `detectChanges()` after an event occurs
+- Is test framework agnostic, it runs on every test framework
diff --git a/docs/angular-testing-library/version-compatibility.mdx b/docs/angular-testing-library/version-compatibility.mdx
new file mode 100644
index 000000000..3b64dd5d2
--- /dev/null
+++ b/docs/angular-testing-library/version-compatibility.mdx
@@ -0,0 +1,18 @@
+---
+id: version-compatibility
+title: Version compatibility
+---
+
+An overview of the compatibility between different versions of Angular Testing
+Library and Angular.
+
+| Angular | Angular Testing Library |
+| ------- | ---------------------------------- |
+| 20.x | 18.x |
+| 19.x | 18.x, 17.x, 16.x, 15.x, 14.x, 13.x |
+| 18.x | 17.x, 16.x, 15.x, 14.x, 13.x |
+| 17.x | 17.x, 16.x, 15.x, 14.x, 13.x |
+| 16.x | 14.x, 13.x |
+| >= 15.1 | 14.x, 13.x |
+| < 15.1 | 12.x, 11.x |
+| 14.x | 12.x, 11.x |
diff --git a/docs/bs-react-testing-library/examples.md b/docs/bs-react-testing-library/examples.mdx
similarity index 97%
rename from docs/bs-react-testing-library/examples.md
rename to docs/bs-react-testing-library/examples.mdx
index ce8d544a7..08e96a7c9 100644
--- a/docs/bs-react-testing-library/examples.md
+++ b/docs/bs-react-testing-library/examples.mdx
@@ -1,6 +1,6 @@
---
id: examples
-title: Examples
+title: Example
---
You can find more bs-dom-testing-library examples at
@@ -11,9 +11,7 @@ You can find more bs-react-testing-library examples at
## React Testing Library
-```reason
-/* Component_test.re */
-
+```reason title="Component_test.re"
open Jest;
open Expect;
open ReactTestingLibrary;
@@ -37,8 +35,7 @@ with typings and creating events.
### getByText
-```reason
-/* __tests__/example_test.re */
+```reason title="__tests__/example_test.re"
open Jest;
open DomTestingLibrary;
open Expect;
diff --git a/docs/bs-react-testing-library/intro.md b/docs/bs-react-testing-library/intro.mdx
similarity index 95%
rename from docs/bs-react-testing-library/intro.md
rename to docs/bs-react-testing-library/intro.mdx
index 8e2545423..316ccc9b2 100644
--- a/docs/bs-react-testing-library/intro.md
+++ b/docs/bs-react-testing-library/intro.mdx
@@ -13,8 +13,11 @@ Bindings for several testing libraries have been ported to [ReasonML][re].
[`bs-dom-testing-library`][gh-dom] contains [BuckleScript][bs] bindings for
`DOM Testing Library`.
-```
+```bash npm2yarn
npm install --save-dev bs-dom-testing-library
+```
+
+```bash npm2yarn
npm install --save-dev bs-react-testing-library
```
@@ -49,7 +52,7 @@ _or_
This is what [BuckleScript][bs] uses to compile the [Reason][re] code to JS. If
it is not in your project you can install it like so:
-```
+```bash npm2yarn
npm install --save-dev bs-platform
```
@@ -60,7 +63,7 @@ examples here will be using it.
- [bs-jest on GitHub](https://github.com/glennsl/bs-jest)
-```
+```bash npm2yarn
npm install --save-dev @glennsl/bs-jest
```
diff --git a/docs/contributing.md b/docs/contributing.md
deleted file mode 100644
index d446eacbe..000000000
--- a/docs/contributing.md
+++ /dev/null
@@ -1,81 +0,0 @@
----
-id: contributing
-title: Contributing
-sidebar_label: Contributing
----
-
-## License
-
-`React Testing Library` is distributed under the open-source MIT license
-
-## Issues
-
-_Looking to contribute? Look for the [Good First Issue][good-first-issue]
-label._
-
-### 🐛 Bugs
-
-Please file an issue for bugs, missing documentation, or unexpected behavior.
-
-[**See Bugs**][bugs]
-
-### 💡 Feature Requests
-
-Please file an issue to suggest new features. Vote on feature requests by adding
-a 👍. This helps maintainers prioritize what to work on.
-
-[**See Feature Requests**][requests]
-
-### ❓ Questions
-
-For questions related to using the library, please visit a support community
-instead of filing an issue on GitHub.
-
-- [Spectrum][spectrum]
-- [Reactiflux on Discord][reactiflux]
-- [Stack Overflow][stackoverflow]
-
-
-
-
-
-[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
-[spectrum-badge]: https://withspectrum.github.io/badge/badge.svg
-[spectrum]: https://spectrum.chat/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"+
-[reactiflux]: https://www.reactiflux.com/
-[stackoverflow]: https://stackoverflow.com/questions/tagged/react-testing-library
-
-
diff --git a/docs/contributing.mdx b/docs/contributing.mdx
new file mode 100644
index 000000000..167844e54
--- /dev/null
+++ b/docs/contributing.mdx
@@ -0,0 +1,49 @@
+---
+id: contributing
+title: Contributing
+sidebar_label: Contributing
+---
+
+## License
+
+`React Testing Library` is distributed under the open-source MIT license
+
+## Issues
+
+_Looking to contribute? Look for the [Good First Issue][good-first-issue]
+label._
+
+### 🐛 Bugs
+
+Please file an issue for bugs, missing documentation, or unexpected behavior.
+
+[**See Bugs**][bugs]
+
+### 💡 Feature Requests
+
+Please file an issue to suggest new features. Vote on feature requests by adding
+a 👍. This helps maintainers prioritize what to work on.
+
+[**See Feature Requests**][requests]
+
+### ❓ Questions
+
+For questions related to using the library, please visit a support community
+instead of filing an issue on GitHub.
+
+- [Discord][discord]
+- [Stack Overflow][stackoverflow]
+
+
+
+
+
+[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"+
+[discord]: https://discord.gg/testing-library
+[stackoverflow]: https://stackoverflow.com/questions/tagged/react-testing-library
+
+
diff --git a/docs/cypress-testing-library/intro.md b/docs/cypress-testing-library/intro.md
deleted file mode 100644
index 4fcf3da49..000000000
--- a/docs/cypress-testing-library/intro.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-id: intro
-title: Cypress Testing Library
----
-
-[`Cypress Testing Library`][gh] allows the use of dom-testing queries within
-[Cypress](https://cypress.io) end-to-end browser tests.
-
-```
-npm install --save-dev cypress @testing-library/cypress
-```
-
-- [Cypress Testing Library on GitHub][gh]
-
-## Usage
-
-`Cypress Testing Library` extends Cypress' `cy` command.
-
-Add this line to your project's `cypress/support/commands.js`:
-
-```
-import '@testing-library/cypress/add-commands';
-```
-
-You can now use all of `DOM Testing Library`'s `getBy`, `getAllBy`, `queryBy`
-and `queryAllBy` commands.
-[See `DOM Testing Library` API for reference](dom-testing-library/api-queries.md)
-
-## Examples
-
-To show some simple examples (from
-[https://github.com/testing-library/cypress-testing-library/blob/master/cypress/integration/commands.spec.js](https://github.com/testing-library/cypress-testing-library/blob/master/cypress/integration/commands.spec.js)):
-
-```javascript
-cy.getAllByText('Jackie Chan').click()
-cy.queryByText('Button Text').should('exist')
-cy.queryByText('Non-existing Button Text').should('not.exist')
-cy.queryByLabelText('Label text', { timeout: 7000 }).should('exist')
-cy.get('form').within(() => {
- cy.getByText('Button Text').should('exist')
-})
-cy.get('form').then(subject => {
- cy.getByText('Button Text', { container: subject }).should('exist')
-})
-```
-
-`Cypress Testing Library` supports both jQuery elements and DOM nodes. This is
-necessary because Cypress uses jQuery elements, while `DOM Testing Library`
-expects DOM nodes. When you pass a jQuery element as `container`, it will get
-the first DOM node from the collection and use that as the `container` parameter
-for the DOM Testing Library functions.
-
-[gh]: https://github.com/testing-library/cypress-testing-library
diff --git a/docs/cypress-testing-library/intro.mdx b/docs/cypress-testing-library/intro.mdx
new file mode 100644
index 000000000..3c88d4d2b
--- /dev/null
+++ b/docs/cypress-testing-library/intro.mdx
@@ -0,0 +1,75 @@
+---
+id: intro
+title: Cypress Testing Library
+---
+
+[`Cypress Testing Library`][gh] allows the use of dom-testing queries within
+[Cypress](https://cypress.io) end-to-end browser tests.
+
+```bash npm2yarn
+npm install --save-dev cypress @testing-library/cypress
+```
+
+- [Cypress Testing Library on GitHub][gh]
+
+## Usage
+
+`Cypress Testing Library` extends Cypress's `cy` commands.
+
+Add this line to your project's `cypress/support/commands.js`:
+
+```js
+import '@testing-library/cypress/add-commands'
+```
+
+You can now use some of `DOM Testing Library`'s `findBy`, and `findAllBy` commands off the global `cy` object.
+[See the `About queries` docs for reference](/docs/queries/about).
+
+> Note: the `get*` queries are not supported because for reasonable Cypress
+> tests you need retryability and `find*` queries already support that. `query*`
+> queries are no longer necessary since v5 and will be removed in v6. `find*`
+> fully support built-in Cypress assertions (removes the only use-case for
+> `query*`).
+
+## With TypeScript
+
+Typings should be added as follows in `tsconfig.json`:
+
+```json
+{
+ "compilerOptions": {
+ "types": ["cypress", "@testing-library/cypress"]
+ }
+}
+```
+
+You can find
+[all Library definitions here](https://github.com/testing-library/cypress-testing-library/blob/master/types/index.d.ts).
+
+## Examples
+
+To show some simple examples (from
+[cypress/integration/find.spec.js](https://github.com/testing-library/cypress-testing-library/blob/97939da7d4707a71049884c0324c0eda56e26fc2/cypress/integration/find.spec.js)):
+
+```javascript
+cy.findByRole('button', {name: /Jackie Chan/i}).click()
+cy.findByRole('button', {name: /Button Text/i}).should('exist')
+cy.findByRole('button', {name: /Non-existing Button Text/i}).should('not.exist')
+cy.findByLabelText(/Label text/i, {timeout: 7000}).should('exist')
+
+// findByRole _inside_ a form element
+cy.get('form')
+ .findByRole('button', {name: /Button Text/i})
+ .should('exist')
+cy.findByRole('dialog').within(() => {
+ cy.findByRole('button', {name: /confirm/i})
+})
+```
+
+`Cypress Testing Library` supports both jQuery elements and DOM nodes. This is
+necessary because Cypress uses jQuery elements, while `DOM Testing Library`
+expects DOM nodes. When you pass a jQuery element as `container`, it will get
+the first DOM node from the collection and use that as the `container` parameter
+for the `DOM Testing Library` functions.
+
+[gh]: https://github.com/testing-library/cypress-testing-library
diff --git a/docs/dom-testing-library/api-accessibility.mdx b/docs/dom-testing-library/api-accessibility.mdx
new file mode 100644
index 000000000..9b5e4e761
--- /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 = `
++ What level of a component tree should I test? Children, parents, or both? +
+ +Following the guiding principle of this library, it is useful to break down how +tests are organized around how the user experiences and interacts with +application functionality rather than around specific components themselves. In +some cases, for example for reusable component libraries, it might be useful to +include developers in the list of users to test for and test each of the +reusable components individually. Other times, the specific break down of a +component tree is just an implementation detail and testing every component +within that tree individually can cause issues (see +https://kentcdodds.com/blog/avoid-the-test-user). + +In practice this means that it is often preferable to test high enough up the +component tree to simulate realistic user interactions. The question of whether +it is worth additionally testing at a higher or lower level on top of this comes +down to a question of tradeoffs and what will provide enough value for the cost +(see https://kentcdodds.com/blog/unit-vs-integration-vs-e2e-tests on more info +on different levels of testing). + +For a more in-depth discussion of this topic see +[this video](https://youtu.be/0qmPdcV-rN8). + +-
+
- Item 1 +
- Item 2 +
-
+
- Item 1 +
- Item 2 +
+// 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..492542440
--- /dev/null
+++ b/docs/dom-testing-library/api-debugging.mdx
@@ -0,0 +1,183 @@
+---
+id: api-debugging
+title: Debugging
+---
+
+## Automatic Logging
+
+When any `get` or `find` calls you use in your test cases fail, 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:
+
+
+```
+
+**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:
+
+```bash npm2yarn
+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).
+
+**Note**: The output of the DOM is colorized by default if your tests are
+running in a node environment. However, you may sometimes want to turn off
+colors, such as in cases where the output is written to a log file for debugging
+purposes. You can use the environment variable `COLORS` to explicitly force the
+colorization off or on. For example:
+
+```bash npm2yarn
+COLORS=false 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/jestjs/jest/tree/main/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
+interface Options extends prettyFormat.OptionsReceived {
+ filterNode?: (node: Node) => boolean
+}
+
+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. In addition to the
+options listed you can also pass the
+[options](https://github.com/jestjs/jest/tree/main/packages/pretty-format#usage-with-options)
+of `pretty-format`.
+
+By default, ``, `` and comment nodes are ignored. You can
+configure this behavior by passing a custom `filterNode` function that should
+return `true` for every node that you wish to include in the output.
+
+This function is usually used alongside `console.log` to temporarily print out
+DOM trees during tests for debugging purposes:
+
+```javascript
+import {prettyDOM} from '@testing-library/dom'
+
+const div = document.createElement('div')
+div.innerHTML = '
+ Hello world
+
+Hello World
+//
+```
+
+This function is what also powers
+[the automatic debugging output described above](#automatic-logging).
+
+## `screen.debug()`
+
+For convenience `screen` also exposes a `debug` method. 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
+ Hello World
+//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 and returns 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'))
+```
+
+## `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 = `
+-
+
- Item 1 +
- Item 2 +
-// 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')
-```
-
-
-
-```js
-import { render, within } from '@testing-library/react'
-
-const { getByLabelText } = render(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:
-
-
-```
-
-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`
-
-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): string
-```
-
-It receives the root node to print out, and an optional extra argument to limit
-the size of the resulting string, for cases when it becomes too large.
-
-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!
-
-Hello World
-//
-```
-
-This function is what also powers
-[the automatic debugging output described above](#debugging).
diff --git a/docs/dom-testing-library/api-queries.md b/docs/dom-testing-library/api-queries.md
deleted file mode 100644
index 6124a29e8..000000000
--- a/docs/dom-testing-library/api-queries.md
+++ /dev/null
@@ -1,744 +0,0 @@
----
-id: api-queries
-title: Queries
----
-
-## Variants
-
-> `getBy` queries are shown by default in the [query documentation](#queries)
-> below.
-
-### getBy
-
-`getBy*` queries returns the first matching node for a query, and throws 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
-throws an error if no elements match.
-
-### queryBy
-
-`queryBy*` queries returns the first matching node for a query, and return
-`null` if no elements match. This is useful for asserting an element is not
-present. This throws 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 `4500`ms. If you need
-to find more than one element, then use `findAllBy`.
-
-> Note, this is a simple combination of `getBy*` queries and
-> [`waitForElement`](/docs/api-async#waitforelement). The `findBy*` queries
-> accept the `waitForElement` options as the last argument. (i.e.
-> `findByText(container, 'text', queryOptions, waitForElementOptions)`)
-
-### 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 `4500`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.
-
-## Queries
-
-### `ByLabelText`
-
-> getByLabelText, queryByLabelText, getAllByLabelText, queryAllByLabelText
-> findByLabelText, findAllByLabelText
-
-```typescript
-getByLabelText(
- container: HTMLElement,
- 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
-
-
-
-// The aria-labelledby attribute with non-form elements
-Hello World
-//Section One
-some content
-