+
+
+
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the
+[all-contributors](https://github.com/all-contributors/all-contributors)
+specification. Contributions of any kind welcome!
diff --git a/website/blog/2018-12-29-new-site.md b/blog/2018-12-29-new-site.mdx
similarity index 79%
rename from website/blog/2018-12-29-new-site.md
rename to blog/2018-12-29-new-site.mdx
index cd3652a16..592607164 100755
--- a/website/blog/2018-12-29-new-site.md
+++ b/blog/2018-12-29-new-site.mdx
@@ -1,7 +1,7 @@
---
title: New Site
author: Alex Krolick
-authorURL: http://github.com/alexkrolick
+authorURL: 'http://github.com/alexkrolick'
---
We have a docs site now! It's built with [Docusaurus](https://docusaurus.io).
@@ -20,6 +20,6 @@ beyond!
🎉 Happy new year!
-[dtl]: /
-[rtl]: /react
-[ctl]: /cypress
+[dtl]: /docs/dom-testing-library/intro
+[rtl]: /docs/react-testing-library/intro
+[ctl]: /docs/cypress-testing-library/intro
diff --git a/website/blog/2019-03-17-code-blocks.md b/blog/2019-03-17-code-blocks.mdx
similarity index 92%
rename from website/blog/2019-03-17-code-blocks.md
rename to blog/2019-03-17-code-blocks.mdx
index 49b0c45b1..b17d70ea2 100755
--- a/website/blog/2019-03-17-code-blocks.md
+++ b/blog/2019-03-17-code-blocks.mdx
@@ -1,7 +1,7 @@
---
title: Multi-Framework Code Blocks
author: Alex Krolick
-authorURL: http://github.com/alexkrolick
+authorURL: 'http://github.com/alexkrolick'
---
Many of the code samples have been updated to include tabs to switch between
diff --git a/website/blog/2019-04-25-new-org.md b/blog/2019-04-25-new-org.mdx
similarity index 83%
rename from website/blog/2019-04-25-new-org.md
rename to blog/2019-04-25-new-org.mdx
index c835f1a8b..b0e09c200 100644
--- a/website/blog/2019-04-25-new-org.md
+++ b/blog/2019-04-25-new-org.mdx
@@ -1,10 +1,12 @@
---
-# prettier doesn't like how long this line is.
-# prettier-ignore
-title: "Testing Library Updates: new release, github org, open collective, and twitter account"
+# prettier doesn't like how long this line is.: ""
+# prettier-ignore: ""
+title:
+ 'Testing Library Updates: new release, github org, open collective, and
+ twitter account'
author: Kent C. Dodds
-authorURL: https://kentcdodds.com
-authorImageURL: https://avatars0.githubusercontent.com/u/1500684?s=120&v=4
+authorURL: 'https://kentcdodds.com/'
+authorImageURL: 'https://avatars0.githubusercontent.com/u/1500684?s=120&v=4'
---
Hello friends! I'm pleased to announce the recent updates to the testing-library
@@ -35,8 +37,7 @@ just disable it here -->
We hope that this helps you catch bugs better!
@@ -71,7 +72,7 @@ Here are the current (or soon to be) members of the org:
(Puppeteer)
- [bs-react-testing-library](https://github.com/wyze/bs-react-testing-library)
(ReasonReact)
-- [testcafe-testing-library](https://github.com/benmonro/testcafe-testing-library)
+- [testcafe-testing-library](https://github.com/testing-library/testcafe-testing-library)
- [user-event](https://github.com/Gpx/user-event)
- [jest-dom](https://github.com/testing-library/jest-dom)
- [jest-native](https://github.com/testing-library/jest-native)
@@ -122,33 +123,27 @@ there.) Please join us!
> [Join us on Spectrum](https://spectrum.chat/testing-library)
-## [Testing Library on React Native](https://www.native-testing-library.com/)
+## [Testing Library on React Native](https://callstack.github.io/react-native-testing-library/)
I'm really happy to announce a super solution to the React Native testing space.
The DOM is quite different from native, as I mentioned before, it's not the code
but the concepts that really make the Testing Library great. I'm happy to say
-that [Brandon Carroll](https://twitter.com/bcarroll22) has successfully ported
+that [Brandon Carroll](https://github.com/bcarroll22) has successfully ported
those concepts to a solution for React Native and I'm really happy with it. Give
it a look if you're building React Native applications and want confidence that
they continue to work as you make changes!
-(Note, there is already `react-native-testing-library`, but it doesn't quite
-follow the guiding principles of Testing Library, so we recommend you use
-`native-testing-library`.
-[Learn More](https://medium.com/@brandoncarroll/why-native-testing-library-exists-629ffb85cae2)).
+> [Checkout native-testing-library](https://callstack.github.io/react-native-testing-library/)
-> [Checkout native-testing-library](https://www.native-testing-library.com/)
-
-## [Learn Testing Library](https://testing-library.com/docs/learning)
+## [Learn Testing Library](/docs/learning)
There's been a LOT of activity around the Testing Library principles and tools
in the content space. We do have
-[a page that lists learning materials](https://testing-library.com/docs/learning),
-and more gets added to it daily. If you know of blog posts, YouTube videos,
-courses, or anything else about the Testing Library family of tools, please
-contribute to the list!
+[a page that lists learning materials](/docs/learning), and more gets added to
+it daily. If you know of blog posts, YouTube videos, courses, or anything else
+about the Testing Library family of tools, please contribute to the list!
-> [Contribute to the learning materials page](https://github.com/testing-library/testing-library-docs/edit/master/docs/learning.md)
+> [Contribute to the learning materials page](https://github.com/testing-library/testing-library-docs/edit/main/docs/learning.mdx)
## Other Exciting news
@@ -157,9 +152,9 @@ As of a few months ago,
you use react-testing-library to test your react applications. That's kinda neat
:)
-At the React Amsterdam [Open Source awards](https://osawards.com/react/) ceremony,
-react-testing-library won the award for the Most impactful contribution to the
-community!
+At the React Amsterdam [Open Source awards](https://osawards.com/react/)
+ceremony, react-testing-library won the award for the Most impactful
+contribution to the community!
@@ -178,7 +173,7 @@ an especially significant impact on the Testing Library family of tools and
community.
[Myself 👋](https://kentcdodds.com), [Alex Krolick](https://alexkrolick.com/),
-[Brandon Carroll](https://twitter.com/bcarroll22),
+[Brandon Carroll](https://github.com/bcarroll22),
[Giorgio](https://twitter.com/Gpx),
[Ernesto García](https://twitter.com/gnapse), and
[Daniel Cook](https://github.com/dfcook).
diff --git a/docker-compose.yml b/docker-compose.yml
deleted file mode 100755
index 6711192ae..000000000
--- a/docker-compose.yml
+++ /dev/null
@@ -1,18 +0,0 @@
-version: "3"
-
-services:
- docusaurus:
- build: .
- ports:
- - 3000:3000
- - 35729:35729
- volumes:
- - ./docs:/app/docs
- - ./website/blog:/app/website/blog
- - ./website/core:/app/website/core
- - ./website/i18n:/app/website/i18n
- - ./website/pages:/app/website/pages
- - ./website/static:/app/website/static
- - ./website/sidebars.json:/app/website/sidebars.json
- - ./website/siteConfig.js:/app/website/siteConfig.js
- working_dir: /app/website
diff --git a/docs/angular-testing-library/api.md b/docs/angular-testing-library/api.md
deleted file mode 100644
index 976e959c9..000000000
--- a/docs/angular-testing-library/api.md
+++ /dev/null
@@ -1,282 +0,0 @@
----
-id: api
-title: API
-sidebar_label: API
----
-
-`Angular Testing Library` re-exports everything from `DOM Testing Library` as
-well as these methods:
-
-- [`render`](<(#render)>)
-
-## `render`
-
-```typescript
-function render(
- component: Type,
- renderOptions?: RenderOptions
-): Promise
-function render(
- template: string,
- renderOptions: RenderOptions
-): Promise
-```
-
-## RenderOptions
-
-### `detectChanges`
-
-Will call `detectChanges` when the component is compiled
-
-**default** : `true`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, { detectChanges: false })
-```
-
-### `declarations`
-
-A collection of providers needed to render the component via Dependency
-Injection, for example, injectable services or tokens.
-
-For more info see the
-[Angular docs](https://angular.io/api/core/NgModule#providers).
-
-**default** : `[]`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- providers: [
- CustomersService,
- {
- provide: MAX_CUSTOMERS_TOKEN,
- useValue: 10,
- },
- ],
-})
-```
-
-### `imports`
-
-A collection of imports needed to render the component, for example, shared
-modules. Adds `NoopAnimationsModule` by default if `BrowserAnimationsModule`
-isn't added to the collection
-
-For more info see the
-[Angular docs](https://angular.io/api/core/NgModule#imports).
-
-**default** : `[NoopAnimationsModule]`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- imports: [AppSharedModule, MaterialModule],
-})
-```
-
-### `schemas`
-
-A collection of schemas needed to render the component. Allowed values are
-`NO_ERRORS_SCHEMA` and `CUSTOM_ELEMENTS_SCHEMA`.
-
-For more info see the
-[Angular docs](https://angular.io/api/core/NgModule#schemas).
-
-**default** : `[]`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- schemas: [NO_ERRORS_SCHEMA],
-})
-```
-
-### `componentProperties`
-
-An object to set `@Input` and `@Output` properties of the component.
-
-**default** : `{}`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- componentProperties: {
- counterValue: 10,
- send: (value) => { ... }
- }
-})
-```
-
-### `componentProviders`
-
-A collection of providers to inject dependencies of the component.
-
-For more info see the
-[Angular docs](https://angular.io/api/core/Directive#providers).
-
-**default** : `[]`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- componentProviders: [AppComponentService],
-})
-```
-
-### `queries`
-
-Queries to bind. Overrides the default set from DOM Testing Library unless
-merged.
-
-**default** : `undefined`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- queries: { ...queries, ...customQueries },
-})
-```
-
-### `wrapper`
-
-An Angular component to wrap the component in.
-
-**default** : `WrapperComponent`, an empty component that strips the
-`ng-version` attribute.
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- wrapper: CustomWrapperComponent,
-})
-```
-
-### `excludeComponentDeclaration`
-
-Exclude the component to be automatically be added as a declaration. This is
-needed when the component is declared in an imported module.
-
-**default** : `false`
-
-**example**:
-
-```typescript
-const component = await render(AppComponent, {
- imports: [AppModule], // a module that includes AppComponent
- excludeComponentDeclaration: true,
-})
-```
-
-## `RenderResult`
-
-### `...queries`
-
-The most important feature of `render` is that the queries from
-[DOM Testing Library](https://testing-library.com/docs/dom-testing-library) are
-automatically returned with their first argument bound to the component under
-test.
-
-See [Queries](https://testing-library.com/docs/dom-testing-library/api-queries)
-for a complete list.
-
-**example**:
-
-```typescript
-const component = await render(AppComponent)
-
-component.getByText('Hello world')
-component.queryByLabelText('First name:')
-```
-
-### `fireEvent.***`
-
-The second most important feature of `render` is that the events from
-[DOM Testing Library](https://testing-library.com/docs/dom-testing-library) are
-automatically bound to the Angular Component. This to ensure that the Angular
-change detection has been run by calling `detectChanges` after an event has been
-fired.
-
-See
-[Firing Events](https://testing-library.com/docs/dom-testing-library/api-events)
-for a complete list.
-
-**example**:
-
-```typescript
-const component = await render(AppComponent)
-
-component.change(component.getByLabelText('Username'), {
- target: {
- value: 'Tim',
- },
-})
-component.click(component.getByText('Login'))
-```
-
-### `type`
-
-Types a value in an input field with the same interactions as the user would do.
-
-```typescript
-const component = await render(AppComponent)
-
-component.type(component.getByLabelText('Username'), 'Tim')
-component.type(component.getByLabelText('Username'), 'Tim', { delay: 250 })
-```
-
-### `selectOptions`
-
-Select an option(s) from a select field with the same interactions as the user
-would do.
-
-```typescript
-const component = await render(AppComponent)
-
-component.selectOptions(component.getByLabelText('Fruit'), 'Blueberry')
-component.selectOptions(component.getByLabelText('Fruit'), ['Blueberry'. 'Grape'])
-```
-
-### `fixture`
-
-The Angular `ComponentFixture` of the component.
-
-For more info see the
-[Angular docs](https://angular.io/api/core/testing/ComponentFixture).
-
-```typescript
-const component = await render(AppComponent)
-
-const componentInstance = component.fixture.componentInstance as AppComponent
-```
-
-> 🚨 If you find yourself using `fixture` to access the component's internal
-> values you should reconsider! This probable means, you're testing
-> implementation details.
-
-### `container`
-
-The containing DOM node of your rendered Angular Component. This is a regular
-DOM node, so you can call `container.querySelector` etc. to inspect the
-children.
-
-### `debug`
-
-Prints out the component's DOM with syntax highlighting. Accepts an optional
-parameter, to print out a specific DOM node.
-
-```typescript
-const component = await render(AppComponent)
-
-component.debug()
-component.debug(component.getByRole('alert'))
-```
diff --git a/docs/angular-testing-library/api.mdx b/docs/angular-testing-library/api.mdx
new file mode 100644
index 000000000..08daa3359
--- /dev/null
+++ b/docs/angular-testing-library/api.mdx
@@ -0,0 +1,597 @@
+---
+id: api
+title: API
+---
+
+`Angular Testing Library` re-exports everything from `DOM Testing Library` as
+well as the `render` method.
+
+The following re-exports are patched to make them easier to use with Angular:
+
+- The events on `fireEvent` automatically invoke a change detection cycle after
+ the event has been fired
+- The `findBy` queries automatically invoke a change detection cycle before the
+ query is invoked function
+- The `waitFor` functions automatically invoke a change detection cycle before
+ invoking the callback function
+
+## `render`
+
+With Angular Testing Library, the component can be rendered in two ways, via the
+component's type or with a template.
+
+> By default, `render` also imports the `NoopAnimationsModule`.
+
+## `Type`
+
+To render a component, you need to pass component's type to the `render` method.
+For components that don't use other parts of your application (for example
+design modules or services), rendering a component can be as simple as the
+following example.
+
+```typescript
+await render(AppComponent)
+```
+
+## `template`
+
+Instead of passing the component's type as first argument, you can also provide
+a template. This practice is required to render directives but can also be
+applied to components, it might even be more useful. The directive's (or
+component's) type must then be added to the `imports` (or `declarations` in case
+of non-standalone components).
+
+**example with directive**:
+
+```typescript
+await render('', {
+ declarations: [SpoilerDirective],
+})
+```
+
+**example with component**:
+
+```typescript
+await render(
+ '',
+ {
+ declarations: [AppComponent],
+ componentProperties: {
+ anotherValue: 'valueOfAnotherProperty',
+ sendValue: jest.fn(),
+ },
+ },
+)
+```
+
+```typescript
+export async function render(
+ component: Type,
+ renderOptions?: RenderComponentOptions,
+): Promise>
+export async function render(
+ template: string,
+ renderOptions?: RenderTemplateOptions,
+): Promise>
+```
+
+## Component RenderOptions
+
+
+### `inputs`
+
+An object to set `@Input` or `input()` properties of the component.
+
+**default** : `{}`
+
+```typescript
+await render(AppComponent, {
+ inputs: {
+ counterValue: 10,
+ // explicitly define aliases using `aliasedInput`
+ ...aliasedInput('someAlias', 'someValue'),
+ },
+})
+```
+
+### `on`
+
+An object with callbacks to subscribe to `EventEmitters` and `Observables` of
+the component.
+
+**default** : `{}`
+
+```ts
+// using a manual callback
+const sendValue = (value) => { ... }
+await render(AppComponent, {
+ on: {
+ send: (value) => sendValue(value),
+ }
+})
+
+// using a (jest) spy
+const sendValueSpy = jest.fn()
+
+await render(AppComponent, {
+ on: {
+ send: sendValueSpy
+ }
+})
+```
+
+### `declarations`
+
+A collection of components, directives and pipes needed to render the component.
+For example, nested components of the component.
+
+For more info see the
+[Angular docs](https://angular.dev/guide/ngmodules/overview#declarations).
+
+**default** : `[]`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ declarations: [CustomerDetailComponent, ButtonComponent],
+})
+```
+
+### `deferBlockBehavior`
+
+Set the defer blocks behavior.
+
+For more info see the
+[Angular docs](https://angular.dev/api/core/testing/DeferBlockBehavior)
+
+**default** : `undefined` (uses `DeferBlockBehavior.Manual`, which is different
+from the Angular default of `DeferBlockBehavior.Playthrough`)
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ deferBlockBehavior: DeferBlockBehavior.Playthrough,
+})
+```
+
+### `deferBlockStates`
+
+Set the initial state of a deferrable blocks in a component.
+
+For more info see the
+[Angular docs](https://angular.dev/api/core/testing/DeferBlockState)
+
+**default** : `undefined` (uses the Angular default, which is
+`DeferBlockState.Placeholder`)
+
+**example**:
+
+```typescript
+await render(FixtureComponent, {
+ deferBlockStates: DeferBlockState.Loading,
+})
+```
+
+### `componentProviders`
+
+A collection of providers needed to render the component via Dependency
+Injection.
+
+These will be provided at the component level. To inject dependencies at the
+module level, use [`providers`](#providers).
+
+For more info see the
+[Angular docs](https://angular.dev/guide/di/hierarchical-dependency-injection#example-providing-services-in-component).
+
+**default** : `[]`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ componentProviders: [AppComponentService],
+})
+```
+
+### `componentImports`
+
+A collection of imports to override a standalone component's imports with.
+
+**default** : `undefined`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ componentImports: [MockChildComponent],
+})
+```
+
+### `childComponentOverrides`
+
+Collection of child component specified providers to override with.
+
+**default** : `undefined`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ childComponentOverrides: [
+ {
+ component: ChildOfAppComponent,
+ providers: [{provide: ChildService, useValue: {hello: 'world'}}],
+ },
+ ],
+})
+```
+
+### `detectChangesOnRender`
+
+Invokes `detectChanges` after the component is rendered.
+
+**default** : `true`
+
+**example**:
+
+```typescript
+await render(AppComponent, {detectChangesOnRender: false})
+```
+
+### `autoDetectChanges`
+
+Automatically detect changes as a "real" running component would do. For
+example, runs a change detection cycle when an event has occured.
+
+**default** : `true`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ autoDetectChanges: false,
+})
+```
+
+### `excludeComponentDeclaration`
+
+Exclude the component to be automatically be added as a declaration. This is
+needed when the component is declared in an imported module, for example with
+SCAMs.
+
+**default** : `false`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ imports: [AppModule], // a module that includes AppComponent
+ excludeComponentDeclaration: true,
+})
+```
+
+### `imports`
+
+A collection of imports needed to render the component, for example, shared
+modules. Adds `NoopAnimationsModule` by default if `BrowserAnimationsModule`
+isn't added to the collection
+
+For more info see the
+[Angular docs](https://angular.dev/guide/components#imports-in-the-component-decorator).
+
+**default** : `[NoopAnimationsModule]`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ imports: [AppSharedModule, MaterialModule],
+})
+```
+
+### `providers`
+
+A collection of providers needed to render the component via Dependency
+Injection.
+
+These will be provided at the module level. To inject dependencies at the
+component level, use [`componentProviders`](#componentProviders).
+
+For more info see the
+[Angular docs](https://angular.dev/guide/di/dependency-injection-providers#).
+
+**default** : `[]`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ providers: [
+ CustomersService,
+ {
+ provide: MAX_CUSTOMERS_TOKEN,
+ useValue: 10,
+ },
+ ],
+})
+```
+
+### `queries`
+
+Queries to bind. Overrides the default set from DOM Testing Library unless
+merged.
+
+**default** : `undefined`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ queries: {...queries, ...customQueries},
+})
+```
+
+### `routes`
+
+The route configuration to set up the router service via
+`RouterTestingModule.withRoutes`. For more info see the
+[Angular Routes docs](https://angular.dev/api/router/Routes).
+
+**default** : `[]`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ declarations: [ChildComponent],
+ routes: [
+ {
+ path: '',
+ children: [
+ {
+ path: 'child/:id',
+ component: ChildComponent,
+ },
+ ],
+ },
+ ],
+})
+```
+
+### `schemas`
+
+A collection of schemas needed to render the component. Allowed values are
+`NO_ERRORS_SCHEMA` and `CUSTOM_ELEMENTS_SCHEMA`.
+
+For more info see the
+[Angular docs](https://angular.dev/guide/components/advanced-configuration#custom-element-schemas).
+
+**default** : `[]`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ schemas: [NO_ERRORS_SCHEMA],
+})
+```
+
+### `removeAngularAttributes`
+
+Removes the Angular attributes (ng-version, and root-id) from the fixture.
+
+**default** : `false`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ removeAngularAttributes: true,
+})
+```
+
+
+### ~~`componentInputs`~~ (deprecated)
+
+An object to set `@Input` properties of the component. Uses `setInput` to set
+the input property. Throws if the component property is not annotated with the
+`@Input` attribute.
+
+**default** : `{}`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ componentInputs: {
+ counterValue: 10,
+ },
+})
+```
+
+### ~~`componentOutputs`~~ (deprecated)
+
+An object to set `@Output` properties of the component.
+
+**default** : `{}`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ componentOutputs: {
+ clicked: (value) => { ... }
+ }
+})
+```
+
+### ~~`componentProperties`~~ (deprecated)
+
+An object to set `@Input` and `@Output` properties of the component. Doesn't
+have a fine-grained control as `inputs` and `on`.
+
+**default** : `{}`
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+ componentProperties: {
+ // an input
+ counterValue: 10,
+ // an output
+ send: (value) => { ... }
+ // a public property
+ name: 'Tim'
+ }
+})
+```
+
+
+## `RenderResult`
+
+### `container`
+
+The containing DOM node of your rendered Angular Component. This is a regular
+DOM node, so you can call `container.querySelector` etc. to inspect the
+children.
+
+### `debug`
+
+Prints out the component's DOM with syntax highlighting. Accepts an optional
+parameter, to print out a specific DOM node.
+
+```typescript
+const {debug} = await render(AppComponent)
+
+debug()
+```
+
+### `rerender`
+
+Changes the input properties of the existing component instance by following
+Angular component lifecycle events (i.e. `ngOnChanges` is called). Input
+properties that are not defined are cleared.
+
+```typescript
+const {rerender} = await render(Counter, {
+ inputs: {count: 4, name: 'Sarah'},
+})
+
+expect(screen.getByTestId('count-value').textContent).toBe('4')
+expect(screen.getByTestId('name-value').textContent).toBe('Sarah')
+
+await rerender({
+ inputs: {count: 7}
+})
+
+// count is updated to 7
+expect(screen.getByTestId('count-value').textContent).toBe('7')
+// name is undefined because it's not provided in rerender
+expect(screen.getByTestId('name-value').textContent).toBeUndefined()
+```
+
+Using `partialUpdate`, only the newly provided properties will be updated. Other
+input properties that aren't provided won't be cleared.
+
+```typescript
+const {rerender} = await render(Counter, {
+ inputs: {count: 4, name: 'Sarah'},
+})
+
+expect(screen.getByTestId('count-value').textContent).toBe('4')
+expect(screen.getByTestId('name-value').textContent).toBe('Sarah')
+
+await rerender({inputs: {count: 7}, partialUpdate: true})
+
+// count is updated to 7
+expect(screen.getByTestId('count-value').textContent).toBe('7')
+// name is still rendered as "Sarah" because of the partial update
+expect(screen.getByTestId('name-value').textContent).toBe('Sarah')
+```
+
+### `detectChanges`
+
+Trigger a change detection cycle for the component.
+
+For more info see the
+[Angular docs](https://angular.dev/api/core/testing/ComponentFixture#detectChanges).
+
+### `debugElement`
+
+The Angular `DebugElement` of the component.
+
+For more info see the [Angular docs](https://angular.dev/api/core/DebugElement).
+
+### `fixture`
+
+The Angular `ComponentFixture` of the component.
+
+For more info see the
+[Angular docs](https://angular.dev/api/core/testing/ComponentFixture).
+
+```typescript
+const {fixture} = await render(AppComponent)
+
+// componentInstance is typed as AppComponent
+const componentInstance = fixture.componentInstance
+```
+
+> 🚨 If you find yourself using `fixture` to access the component's internal
+> values you should reconsider! This probable means, you're testing
+> implementation details.
+
+### `navigate`
+
+Accepts a DOM element or a path as parameter. If an element is passed,
+`navigate` will navigate to the `href` value of the element. If a path is
+passed, `navigate` will navigate to the path.
+
+```typescript
+const { navigate } = await render(AppComponent, {
+ routes: [...]
+})
+
+await navigate(component.getByLabelText('To details'))
+await navigate('details/3')
+```
+
+### `...queries`
+
+The most important feature of `render` is that the queries from
+[DOM Testing Library](/docs/dom-testing-library/intro) are automatically
+returned with their first argument bound to the component under test.
+
+See [Queries](queries/about.mdx) for a complete list.
+
+**example**:
+
+```typescript
+const {getByText, queryByLabelText} = await render(AppComponent)
+
+screen.getByRole('heading', {
+ name: /api/i,
+})
+queryByLabelText(/First name/i')
+```
+
+### `renderDeferBlock`
+
+To test [Deferrable views](https://angular.dev/guide/defer#defer), you can make
+use of `renderDeferBlock`. `renderDeferBlock` will set the desired defer state
+for a specific deferrable block. The default value of a deferrable view is
+`Placeholder`, but you can also set the initial state while rendering the
+component.
+
+```typescript
+const {renderDeferBlock} = await render(FixtureComponent, {
+ deferBlockStates: DeferBlockState.Loading,
+})
+
+expect(screen.getByText(/loading/i)).toBeInTheDocument()
+
+await renderDeferBlock(DeferBlockState.Complete)
+expect(screen.getByText(/completed/i)).toBeInTheDocument()
+```
diff --git a/docs/angular-testing-library/examples.md b/docs/angular-testing-library/examples.md
deleted file mode 100644
index ad2e2cd35..000000000
--- a/docs/angular-testing-library/examples.md
+++ /dev/null
@@ -1,69 +0,0 @@
----
-id: examples
-title: Examples
-sidebar_label: Examples
----
-
-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'))
- })
-})
-```
-
-More examples can be found in the
-[GitHub project](https://github.com/testing-library/angular-testing-library/tree/master/src/app/examples).
-These examples include:
-
-- `@Input` and `@Output` properties
-- (Reactive) Forms
-- Integration with NgRx (mock) Store
-- And more
-
-If you're looking for an example that isn't on the list, please feel free to
-create a
-[new issue](https://github.com/testing-library/angular-testing-library/issues/new).
diff --git a/docs/angular-testing-library/examples.mdx b/docs/angular-testing-library/examples.mdx
new file mode 100644
index 000000000..2e44b893c
--- /dev/null
+++ b/docs/angular-testing-library/examples.mdx
@@ -0,0 +1,82 @@
+---
+id: examples
+title: Example
+---
+
+> Read about
+> [best practices](https://timdeschryver.dev/blog/good-testing-practices-with-angular-testing-library),
+> or follow the
+> [guided example](https://timdeschryver.dev/blog/getting-the-most-value-out-of-your-angular-component-tests)
+
+Angular Testing Library can be used with standalone components and also with Angular components that uses Modules.
+The example below shows how to test a standalone component, but the same principles apply to Angular components that uses Modules.
+In fact, there should be no difference in how you test both types of components, only the setup might be different.
+
+```ts title="counter.component.ts"
+@Component({
+ selector: 'app-counter',
+ template: `
+ {{ hello() }}
+
+ Current Count: {{ counter() }}
+
+ `,
+})
+export class CounterComponent {
+ counter = model(0);
+ hello = input('Hi', { alias: 'greeting' });
+
+ increment() {
+ this.counter.set(this.counter() + 1);
+ }
+
+ decrement() {
+ this.counter.set(this.counter() - 1);
+ }
+}
+```
+
+```typescript title="counter.component.spec.ts"
+import { render, screen, fireEvent, aliasedInput } from '@testing-library/angular';
+import { CounterComponent } from './counter.component';
+
+describe('Counter', () => {
+ it('should render counter', async () => {
+ await render(CounterComponent, {
+ inputs: {
+ counter: 5,
+ // aliases need to be specified using aliasedInput
+ ...aliasedInput('greeting', 'Hello Alias!'),
+ },
+ });
+
+ expect(screen.getByText('Current Count: 5')).toBeVisible();
+ expect(screen.getByText('Hello Alias!')).toBeVisible();
+ });
+
+ it('should increment the counter on click', async () => {
+ await render(CounterComponent, { inputs: { counter: 5 } });
+
+ const incrementButton = screen.getByRole('button', { name: '+' });
+ fireEvent.click(incrementButton);
+
+ expect(screen.getByText('Current Count: 6')).toBeVisible();
+ });
+});
+```
+
+## More examples
+
+More examples can be found in the
+[GitHub project](https://github.com/testing-library/angular-testing-library/tree/master/apps/example-app/src/app/examples).
+These examples include:
+
+- `input` and `output` properties
+- Forms
+- Integration injected services
+- And
+ [more](https://github.com/testing-library/angular-testing-library/tree/master/apps/example-app/src/app/examples)
+
+If you're looking for an example that isn't on the list, please feel free to
+create a
+[new issue](https://github.com/testing-library/angular-testing-library/issues/new).
diff --git a/docs/angular-testing-library/faq.mdx b/docs/angular-testing-library/faq.mdx
new file mode 100644
index 000000000..e333db4b3
--- /dev/null
+++ b/docs/angular-testing-library/faq.mdx
@@ -0,0 +1,109 @@
+---
+id: faq
+title: FAQ
+---
+
+See also the [main FAQ](dom-testing-library/faq.mdx) for questions not specific
+to Angular testing.
+
+
+
+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: '',
+})
+class ParentComponent {}
+
+@Component({
+ selector: 'app-child-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()
+ })
+})
+```
+
+
+
+
+
+
+ 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).
+
+
+
+
+
+
+
+[guiding-principle]: https://twitter.com/kentcdodds/status/977018512689455106
+
+
diff --git a/docs/angular-testing-library/intro.md b/docs/angular-testing-library/intro.mdx
similarity index 82%
rename from docs/angular-testing-library/intro.md
rename to docs/angular-testing-library/intro.mdx
index 42d30e6ff..a7820b7f0 100644
--- a/docs/angular-testing-library/intro.md
+++ b/docs/angular-testing-library/intro.mdx
@@ -8,9 +8,17 @@ sidebar_label: Introduction
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
-npm install --save-dev @testing-library/angular
+ng add @testing-library/angular
```
- [`@testing-library/angular-testing-library` on GitHub](https://github.com/testing-library/angular-testing-library)
@@ -33,11 +41,11 @@ components. It provides light utility functions on top of
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.md)
+> [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 for elements by their
+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
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 bbc7cefee..000000000
--- a/docs/cypress-testing-library/intro.md
+++ /dev/null
@@ -1,68 +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's `cy` commands.
-
-Add this line to your project's `cypress/support/commands.js`:
-
-```
-import '@testing-library/cypress/add-commands';
-```
-
-## With TypeScript
-
-Typings are defined in `@types/testing-library__cypress` at [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress),
-and should be added as follows in `tsconfig.json`:
-
-```json
-{
- "compilerOptions": {
- "types": ["cypress", "@types/testing-library__cypress"]
- }
-}
-```
-
-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
-
-You can find [all library definitions here](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress/index.d.ts).
-
-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 = `
+
],
+// 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.md b/docs/dom-testing-library/api-async.md
deleted file mode 100644
index 24008c9db..000000000
--- a/docs/dom-testing-library/api-async.md
+++ /dev/null
@@ -1,260 +0,0 @@
----
-id: api-async
-title: Async Utilities
----
-
-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.md).)
-
-## `wait`
-
-```typescript
-function wait(
- callback?: () => void,
- options?: {
- timeout?: number
- interval?: number
- }
-): Promise
-```
-
-When in need to wait for non-deterministic periods of time you can use `wait`,
-to wait for your expectations to pass. The `wait` function is a small wrapper
-around the
-[`wait-for-expect`](https://github.com/TheBrainFamily/wait-for-expect) module.
-Here's a simple example:
-
-```javascript
-// ...
-// Wait until the callback does not throw an error. In this case, that means
-// it'll wait until we can get a form control with a label that matches "username".
-await wait(() => getByLabelText(container, 'username'))
-getByLabelText(container, 'username').value = 'chucknorris'
-// ...
-```
-
-This can be useful if you have a unit test that mocks API calls and you need to
-wait for your mock promises to all resolve.
-
-The default `callback` is a no-op function (used like `await wait()`). This can
-be helpful if you only need to wait for one tick of the event loop (in the case
-of mocked API calls with promises that resolve immediately).
-
-The default `timeout` is `4500ms` which will keep you under
-[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).
-
-The default `interval` is `50ms`. However it will run your callback immediately
-on the next tick of the event loop (in a `setTimeout`) before starting the
-intervals.
-
-## `waitForElement`
-
-```typescript
-function waitForElement(
- callback: () => T,
- options?: {
- container?: HTMLElement
- timeout?: number
- mutationObserverOptions?: MutationObserverInit
- }
-): Promise
-```
-
-When in need to wait for DOM elements to appear, disappear, or change you can
-use `waitForElement`. The `waitForElement` function is a small wrapper around
-the
-[`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
-
-Here's a simple example:
-
-```javascript
-// ...
-// Wait until the callback does not throw an error and returns a truthy value. In this case, that means
-// it'll wait until we can get a form control with a label that matches "username".
-// The difference from `wait` is that rather than running your callback on
-// an interval, it's run as soon as there are DOM changes in the container
-// and returns the value returned by the callback.
-const usernameElement = await waitForElement(
- () => getByLabelText(container, 'username'),
- { container }
-)
-usernameElement.value = 'chucknorris'
-// ...
-```
-
-You can also wait for multiple elements at once:
-
-```javascript
-const [usernameElement, passwordElement] = await waitForElement(
- () => [
- getByLabelText(container, 'username'),
- getByLabelText(container, 'password'),
- ],
- { container }
-)
-```
-
-Using
-[`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
-is more efficient than polling the DOM at regular intervals with `wait`. This
-library sets up a
-[`'mutationobserver-shim'`](https://github.com/megawac/MutationObserver.js) on
-the global `window` object for cross-platform compatibility with older browsers
-and the [`jsdom`](https://github.com/jsdom/jsdom/issues/639) that is usually
-used in Node-based tests.
-
-The default `container` is the global `document`. Make sure the elements you
-wait for will be attached to it, or set a different `container`.
-
-The default `timeout` is `4500ms` which will keep you under
-[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).
-
-The default `mutationObserverOptions` is
-`{subtree: true, childList: true, attributes: true, characterData: true}` which
-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.
-
-## `waitForDomChange`
-
-```typescript
-function waitForDomChange(options?: {
- container?: HTMLElement
- timeout?: number
- mutationObserverOptions?: MutationObserverInit
-}): Promise
-```
-
-When in need to wait for the DOM to change you can use `waitForDomChange`. The
-`waitForDomChange` function is a small wrapper around the
-[`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
-
-Here is an example where the promise will be resolved because the container is
-changed:
-
-```javascript
-const container = document.createElement('div')
-waitForDomChange({ container })
- .then(() => console.log('DOM changed!'))
- .catch(err => console.log(`Error you need to deal with: ${err}`))
-container.append(document.createElement('p'))
-// if 👆 was the only code affecting the container and it was not run,
-// waitForDomChange would throw an error
-```
-
-The promise will resolve with a
-[`mutationsList`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/MutationObserver)
-which you can use to determine what kind of a change (or changes) affected the
-container
-
-```javascript
-const container = document.createElement('div')
-container.setAttribute('data-cool', 'true')
-waitForDomChange({ container }).then(mutationsList => {
- const mutation = mutationsList[0]
- console.log(
- `was cool: ${mutation.oldValue}\ncurrently cool: ${
- mutation.target.dataset.cool
- }`
- )
-})
-container.setAttribute('data-cool', 'false')
-/*
- logs:
- was cool: true
- currently cool: false
-*/
-```
-
-Using
-[`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
-is more efficient than polling the DOM at regular intervals with `wait`. This
-library sets up a
-[`'mutationobserver-shim'`](https://github.com/megawac/MutationObserver.js) on
-the global `window` object for cross-platform compatibility with older browsers
-and the [`jsdom`](https://github.com/jsdom/jsdom/issues/639) that is usually
-used in Node-based tests.
-
-The default `container` is the global `document`. Make sure the elements you
-wait for will be attached to it, or set a different `container`.
-
-The default `timeout` is `4500ms` which will keep you under
-[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).
-
-The default `mutationObserverOptions` is
-`{subtree: true, childList: true, attributes: true, characterData: true}` which
-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.
-
-## `waitForElementToBeRemoved`
-
-```typescript
-function waitForElementToBeRemoved(
- callback: () => T,
- options?: {
- container?: HTMLElement
- timeout?: number
- mutationObserverOptions?: MutationObserverInit
- }
-): Promise
-```
-
-To wait for the removal of element(s) from the DOM you can use
-`waitForElementToBeRemoved`. The `waitForElementToBeRemoved` function is a small
-wrapper around the
-[`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
-
-The callback must return the pre-existing element or array of elements that are
-expected to be removed.
-
-Here is an example where the promise resolves with `true` because the element is
-removed:
-
-```javascript
-const el = document.querySelector('div.getOuttaHere')
-
-waitForElementToBeRemoved(() =>
- document.querySelector('div.getOuttaHere')
-).then(() => console.log('Element no longer in DOM'))
-
-el.setAttribute('data-neat', true)
-// other mutations are ignored...
-
-el.parentElement.removeChild(el)
-// logs 'Element no longer in DOM'
-```
-
-`waitForElementToBeRemoved` will throw an error when the provided callback does
-not return an element.
-
-```javascript
-waitForElementToBeRemoved(() => null).catch(err => console.log(err))
-
-// 'The callback function which was passed did not return an element
-// or non-empty array of elements.
-// waitForElementToBeRemoved requires that the element(s) exist
-// before waiting for removal.'
-```
-
-Using
-[`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
-is more efficient than polling the DOM at regular intervals with `wait`. This
-library sets up a
-[`'mutationobserver-shim'`](https://github.com/megawac/MutationObserver.js) on
-the global `window` object for cross-platform compatibility with older browsers
-and the [`jsdom`](https://github.com/jsdom/jsdom/issues/639) that is usually
-used in Node-based tests.
-
-The default `container` is the global `document`. Make sure the elements you
-wait for are descendants of `container`.
-
-The default `timeout` is `4500ms` which will keep you under
-[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).
-
-The default `mutationObserverOptions` is
-`{subtree: true, childList: true, attributes: true, characterData: true}` which
-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-async.mdx b/docs/dom-testing-library/api-async.mdx
new file mode 100644
index 000000000..700fbe81d
--- /dev/null
+++ b/docs/dom-testing-library/api-async.mdx
@@ -0,0 +1,146 @@
+---
+id: api-async
+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 event,
+user action, timeout, or Promise. (See the
+[guide to testing disappearance](guide-disappearance.mdx).)
+
+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`
+
+```typescript
+function waitFor(
+ callback: () => T | Promise,
+ options?: {
+ container?: HTMLElement
+ timeout?: number
+ interval?: number
+ onTimeout?: (error: Error) => Error
+ mutationObserverOptions?: MutationObserverInit
+ },
+): Promise
+```
+
+When in need to wait for any period of time you can use `waitFor`, to wait for
+your expectations to pass. Returning _a falsy condition is not sufficient_ to
+trigger a retry, the callback must throw an error in order to retry the
+condition. Here's a simple example:
+
+```javascript
+// ...
+// Wait until the callback does not throw an error. In this case, that means
+// it'll wait until the mock function has been called once.
+await waitFor(() => expect(mockAPI).toHaveBeenCalledTimes(1))
+// ...
+```
+
+`waitFor` may run the callback a number of times until the timeout is reached.
+Note that the number of calls is constrained by the `timeout` and `interval`
+options.
+
+This can be useful if you have a unit test that mocks API calls and you need to
+wait for your mock promises to all resolve.
+
+If you return a promise in the `waitFor` callback (either explicitly or
+implicitly with the `async` syntax), then the `waitFor` utility does not call
+your callback again until that promise rejects. This allows you to `waitFor`
+things that must be checked asynchronously.
+
+The default `container` is the global `document`. Make sure the elements you
+wait for are descendants of `container`.
+
+The default `interval` is `50ms`. However it runs your callback immediately
+before starting the intervals.
+
+The default `timeout` is `1000ms`.
+
+The default `onTimeout` takes the error and appends the `container`'s printed
+state to the error message which should hopefully make it easier to track down
+what caused the timeout.
+
+The default `mutationObserverOptions` is
+`{subtree: true, childList: true, attributes: true, characterData: true}` which
+detects additions and removals of child elements (including text nodes) in the
+`container` and any of its descendants. It also detects attribute changes. When
+any of those changes occur, it re-runs the callback.
+
+## `waitForElementToBeRemoved`
+
+```typescript
+function waitForElementToBeRemoved(
+ callback: (() => T) | T,
+ options?: {
+ container?: HTMLElement
+ timeout?: number
+ interval?: number
+ onTimeout?: (error: Error) => Error
+ mutationObserverOptions?: MutationObserverInit
+ },
+): Promise
+```
+
+To wait for the removal of element(s) from the DOM you can use
+`waitForElementToBeRemoved`. The `waitForElementToBeRemoved` function is a small
+wrapper around the `waitFor` utility.
+
+The first argument must be an element, array of elements, or a callback which
+returns an element or array of elements.
+
+Here is an example where the promise resolves because the element is removed:
+
+```javascript
+const el = document.querySelector('div.getOuttaHere')
+
+waitForElementToBeRemoved(document.querySelector('div.getOuttaHere')).then(() =>
+ console.log('Element no longer in DOM'),
+)
+
+el.setAttribute('data-neat', true)
+// other mutations are ignored...
+
+el.parentElement.removeChild(el)
+// logs 'Element no longer in DOM'
+```
+
+`waitForElementToBeRemoved` throws an error if the first argument is `null` or
+an empty array:
+
+```javascript
+waitForElementToBeRemoved(null).catch(err => console.log(err))
+waitForElementToBeRemoved(queryByText(/not here/i)).catch(err =>
+ console.log(err),
+)
+waitForElementToBeRemoved(queryAllByText(/not here/i)).catch(err =>
+ console.log(err),
+)
+waitForElementToBeRemoved(() => getByText(/not here/i)).catch(err =>
+ console.log(err),
+)
+
+// Error: The element(s) given to waitForElementToBeRemoved are already removed. waitForElementToBeRemoved requires that the element(s) exist(s) before waiting for removal.
+```
+
+The options object is forwarded to `waitFor`.
diff --git a/docs/dom-testing-library/api-configuration.md b/docs/dom-testing-library/api-configuration.md
deleted file mode 100644
index 660495d02..000000000
--- a/docs/dom-testing-library/api-configuration.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-id: api-configuration
-title: Configuration
----
-
-## Configuration
-
-The library can be configured via the `configure` function, which accepts:
-
-- a plain JS object; this will be merged into the existing configuration. e.g.
- `configure({testIdAttribute: 'not-data-testid'})`
-- a function; the function will be given the existing configuration, and should
- return a plain JS object which will be merged as above, e.g.
- `configure(existingConfig => ({something: [...existingConfig.something, 'extra value for the something array']}))`
-
-Configuration options:
-
-`testIdAttribute`: The attribute used by `getByTestId` and related queries.
-Defaults to `data-testid`. See [`getByTestId`](#getbytestid).
-
-
-
-
-
-```js
-// setup-tests.js
-import { configure } from '@testing-library/dom'
-
-configure({testIdAttribute: 'my-data-test-id'})`
-```
-
-
-
-```js
-// setup-tests.js
-import { configure } from '@testing-library/react'
-
-configure({testIdAttribute: 'my-data-test-id'})`
-```
-
-
-
-```
-The configuration object is not currently exposed to in Cypress Testing Library
-```
-
-
diff --git a/docs/dom-testing-library/api-configuration.mdx b/docs/dom-testing-library/api-configuration.mdx
new file mode 100644
index 000000000..72dd2e196
--- /dev/null
+++ b/docs/dom-testing-library/api-configuration.mdx
@@ -0,0 +1,177 @@
+---
+id: api-configuration
+title: Configuration Options
+---
+
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+## Introduction
+
+The library can be configured via the `configure` function, which accepts:
+
+- a plain JS object; this will be merged into the existing configuration. e.g.
+ `configure({testIdAttribute: 'not-data-testid'})`
+- a function; the function will be given the existing configuration, and should
+ return a plain JS object which will be merged as above, e.g.
+ `configure(existingConfig => ({something: [...existingConfig.something, 'extra value for the something array']}))`
+
+> **Note**
+>
+> Framework-specific wrappers like React Testing Library may add more options to
+> the ones shown below.
+
+
+
+
+```js title="setup-tests.js"
+import {configure} from '@testing-library/dom'
+import serialize from 'my-custom-dom-serializer'
+
+configure({
+ testIdAttribute: 'data-my-test-id',
+ getElementError: (message, container) => {
+ const customMessage = [message, serialize(container.firstChild)].join(
+ '\n\n',
+ )
+ return new Error(customMessage)
+ },
+})
+```
+
+
+
+
+```js title="setup-tests.js"
+import {configure} from '@testing-library/react'
+
+configure({testIdAttribute: 'data-my-test-id'})
+```
+
+
+
+
+```ts title="setup-tests.ts"
+import {configure} from '@testing-library/angular'
+
+configure({
+ dom: {
+ testIdAttribute: 'data-my-test-id',
+ },
+})
+```
+
+
+
+
+```js title="setup-tests.js"
+import {configure} from '@testing-library/cypress'
+
+configure({testIdAttribute: 'data-my-test-id'})
+```
+
+
+
+
+## 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`](https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle)
+with a second argument e.g.
+`window.getComputedStyle(document.createElement('div'), '::after')`. Defaults to
+`false`
+
+### `defaultHidden`
+
+The default value for the [`hidden` option](queries/byrole#hidden) used by
+[`getByRole`](queries/byrole.mdx). Defaults to `false`.
+
+### `defaultIgnore`
+
+The default value for the [`ignore` option](queries/bytext.mdx#ignore) used by
+[`getByText`](queries/bytext.mdx). Also determines the nodes that are being
+ignored when errors are printed.
+
+Defaults to `script, style`.
+
+### `showOriginalStackTrace`
+
+By default, [`waitFor`](api-async#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](queries/about.mdx#priority) are available, the
+test will fail and provide a suggested query to use instead. Defaults to
+`false`.
+
+To disable a suggestion for a single query just add `{suggest:false}` as an
+option.
+
+```js
+screen.getByTestId('foo', {suggest: false}) // will not throw a suggestion
+```
+
+:::note
+
+When this option is enabled, it may provide suggestions that lack an intuitive
+implementation. Typically this happens for
+[roles which cannot be named](https://w3c.github.io/aria/#namefromprohibited),
+most notably paragraphs. For instance, if you attempt to use
+[`getByText`](queries/bytext.mdx), you may encounter the following error:
+
+```
+TestingLibraryElementError: A better query is available, try this:
+ getByRole('paragraph')
+```
+
+However, there is no direct way to query paragraphs using the config object
+parameter, such as in `getByRole('paragraph', { name: 'Hello World' })`.
+
+To address this issue, you can leverage a custom function to validate the
+element's structure, as shown in the example below. More information can be
+found in the
+[GitHub issue](https://github.com/testing-library/dom-testing-library/issues/1306)
+
+```js
+getByRole('paragraph', {
+ name: (_, element) => element.textContent === 'Hello world',
+})
+```
+
+:::
+
+### `testIdAttribute`
+
+The attribute used by [`getByTestId`](queries/bytestid.mdx) and related queries.
+Defaults to `data-testid`.
+
+### `getElementError`
+
+A function that returns the error used when
+[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`](api-async#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..8147ead50
--- /dev/null
+++ b/docs/dom-testing-library/api-custom-queries.mdx
@@ -0,0 +1,119 @@
+---
+id: api-custom-queries
+title: 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 title="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(container, id, ...rest) {
+ // result >= 1
+ const result = getAllByTestId(container, id, ...rest)
+ if (result.length > 1) {
+ throw queryHelpers.getElementError(
+ `Found multiple elements with the [data-test-id="${id}"]`,
+ container,
+ )
+ }
+ return result[0]
+}
+
+// re-export with overrides
+module.exports = {
+ ...domTestingLib,
+ getByTestId,
+ getAllByTestId,
+ queryByTestId,
+ queryAllByTestId,
+}
+```
+
+## `buildQueries`
+
+The `buildQueries` helper allows you to create custom queries with all the
+[standard queries](queries/about.mdx) 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..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:
+
+
+ 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:
+
+```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
'
+console.log(prettyDOM(div))
+//
+//
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
+
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 = `
+
+--------------------------------------------------
+listitem:
+
+
+--------------------------------------------------
+```
diff --git a/docs/dom-testing-library/api-events.md b/docs/dom-testing-library/api-events.md
deleted file mode 100644
index 736c94bba..000000000
--- a/docs/dom-testing-library/api-events.md
+++ /dev/null
@@ -1,95 +0,0 @@
----
-id: api-events
-title: Firing Events
----
-
-## `fireEvent`
-
-```typescript
-fireEvent(node: HTMLElement, event: Event)
-```
-
-Fire DOM events.
-
-```javascript
-//
-fireEvent(
- getByText(container, 'Submit'),
- new MouseEvent('click', {
- bubbles: true,
- cancelable: true,
- })
-)
-```
-
-## `fireEvent[eventName]`
-
-```typescript
-fireEvent[eventName](node: HTMLElement, eventProperties: Object)
-```
-
-Convenience methods for firing DOM events. Check out
-[src/events.js](https://github.com/testing-library/dom-testing-library/blob/master/src/events.js)
-for a full list as well as default `eventProperties`.
-
-```javascript
-//
-const rightClick = { button: 2 }
-fireEvent.click(getByText('Submit'), rightClick)
-// default `button` property for click events is set to `0` which is a left click.
-```
-
-**target**: When an event is dispatched on an element, the event has the
-subjected element on a property called `target`. As a convenience, if you
-provide a `target` property in the `eventProperties` (second argument), then
-those properties will be assigned to the node which is receiving the event.
-
-This is particularly useful for a change event:
-
-```javascript
-fireEvent.change(getByLabelText(/username/i), { target: { value: 'a' } })
-
-// note: attempting to manually set the files property of an HTMLInputElement
-// results in an error as the files property is read-only.
-// this feature works around that by using Object.defineProperty.
-fireEvent.change(getByLabelText(/picture/i), {
- target: {
- files: [new File(['(⌐□_□)'], 'chucknorris.png', { type: 'image/png' })],
- },
-})
-```
-
-**Keyboard events**: There are three event types related to keyboard input -
-`keyPress`, `keyDown`, and `keyUp`. When firing these you need to reference an
-element in the DOM and the key you want to fire.
-
-```javascript
-fireEvent.keyDown(domNode, { key: 'Enter', code: 13 })
-
-// note: you should set the charCode or it will be fallback to 0
-// will Fire an KeyboardEvent with charCode = 0
-fireEvent.keyDown(domNode, { key: 'Enter', code: 13 })
-
-// will Fire an KeyboardEvent with charCode = 65
-fireEvent.keyDown(domNode, { key: 'A', code: 65, charCode: 65 })
-```
-
-You can find out which key code to use at
-[https://keycode.info/](https://keycode.info/).
-
-## `createEvent[eventName]`
-
-```typescript
-createEvent[eventName](node: HTMLElement, eventProperties: Object)
-```
-
-Convenience methods for creating DOM events that can then be fired by
-`fireEvent`, allowing you to have a reference to the event created: this might
-be useful if you need to access event properties that cannot be initiated
-programmatically (such as `timeStamp`).
-
-```javascript
-const myEvent = createEvent.click(node, { button: 2 })
-fireEvent(node, myEvent)
-// myEvent.timeStamp can be accessed just like any other properties from myEvent
-```
diff --git a/docs/dom-testing-library/api-events.mdx b/docs/dom-testing-library/api-events.mdx
new file mode 100644
index 000000000..614ff1689
--- /dev/null
+++ b/docs/dom-testing-library/api-events.mdx
@@ -0,0 +1,191 @@
+---
+id: api-events
+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`](user-event/intro.mdx).
+
+## `fireEvent`
+
+```typescript
+fireEvent(node: HTMLElement, event: Event)
+```
+
+Fire DOM events.
+
+```javascript
+//
+fireEvent(
+ getByText(container, 'Submit'),
+ new MouseEvent('click', {
+ bubbles: true,
+ cancelable: true,
+ }),
+)
+```
+
+## `fireEvent[eventName]`
+
+```typescript
+fireEvent[eventName](node: HTMLElement, eventProperties: Object)
+```
+
+Convenience methods for firing DOM events. Check out
+[src/event-map.js](https://github.com/testing-library/dom-testing-library/blob/master/src/event-map.js)
+for a full list as well as default `eventProperties`.
+
+**target**: When an event is dispatched on an element, the event has the
+subjected element on a property called `target`. As a convenience, if you
+provide a `target` property in the `eventProperties` (second argument), then
+those properties will be assigned to the node which is receiving the event.
+
+This is particularly useful for a change event:
+
+```javascript
+fireEvent.change(getByLabelText(/username/i), {target: {value: 'a'}})
+
+// note: attempting to manually set the files property of an HTMLInputElement
+// results in an error as the files property is read-only.
+// this feature works around that by using Object.defineProperty.
+fireEvent.change(getByLabelText(/picture/i), {
+ target: {
+ files: [new File(['(⌐□_□)'], 'chucknorris.png', {type: 'image/png'})],
+ },
+})
+
+// Note: The 'value' attribute must use ISO 8601 format when firing a
+// change event on an input of type "date". Otherwise the element will not
+// reflect the changed value.
+
+// Invalid:
+fireEvent.change(input, {target: {value: '24/05/2020'}})
+
+// Valid:
+fireEvent.change(input, {target: {value: '2020-05-24'}})
+```
+
+**dataTransfer**: Drag events have a `dataTransfer` property that contains data
+transferred during the operation. As a convenience, if you provide a
+`dataTransfer` property in the `eventProperties` (second argument), then those
+properties will be added to the event.
+
+This should predominantly be used for testing drag and drop interactions.
+
+```javascript
+fireEvent.drop(getByLabelText(/drop files here/i), {
+ dataTransfer: {
+ files: [new File(['(⌐□_□)'], 'chucknorris.png', {type: 'image/png'})],
+ },
+})
+```
+
+**Keyboard events**: There are three event types related to keyboard input -
+`keyPress`, `keyDown`, and `keyUp`. When firing these you need to reference an
+element in the DOM and the key you want to fire.
+
+```javascript
+fireEvent.keyDown(domNode, {key: 'Enter', code: 'Enter', charCode: 13})
+
+fireEvent.keyDown(domNode, {key: 'A', code: 'KeyA'})
+```
+
+You can find out which key code to use at
+[https://www.toptal.com/developers/keycode](https://www.toptal.com/developers/keycode).
+
+## `createEvent[eventName]`
+
+```typescript
+createEvent[eventName](node: HTMLElement, eventProperties: Object)
+```
+
+Convenience methods for creating DOM events that can then be fired by
+`fireEvent`, allowing you to have a reference to the event created: this might
+be useful if you need to access event properties that cannot be initiated
+programmatically (such as `timeStamp`).
+
+```javascript
+const myEvent = createEvent.click(node, {button: 2})
+fireEvent(node, myEvent)
+// myEvent.timeStamp can be accessed just like any other properties from myEvent
+// note: The access to the events created by `createEvent` is based on the native event API,
+// Therefore, native properties of HTMLEvent object (e.g. `timeStamp`, `cancelable`, `type`) should be set using Object.defineProperty
+// For more info see: https://developer.mozilla.org/en-US/docs/Web/API/Event
+```
+
+You can also create generic events:
+
+```javascript
+// simulate the 'input' event on a file input
+fireEvent(
+ input,
+ createEvent('input', input, {
+ target: {files: inputFiles},
+ ...init,
+ }),
+)
+```
+
+## Using Jest Function Mocks
+
+[Jest's Mock functions](https://jestjs.io/docs/en/mock-functions) can be used to
+test that a component will call its bound callback in response to a particular
+event.
+
+
+
+
+```jsx
+import {render, screen, fireEvent} from '@testing-library/react'
+
+const Button = ({onClick, children}) => (
+
+)
+
+test('calls onClick prop when clicked', () => {
+ const handleClick = jest.fn()
+ render()
+ fireEvent.click(screen.getByText(/click me/i))
+ expect(handleClick).toHaveBeenCalledTimes(1)
+})
+```
+
+
+
+
+```ts
+import {render, screen, fireEvent} from '@testing-library/angular'
+
+@Component({
+ template: ``,
+})
+class ButtonComponent {
+ @Output() handleClick = new EventEmitter()
+}
+
+test('calls onClick prop when clicked', async () => {
+ const handleClick = jest.fn()
+ await render(ButtonComponent, {
+ componentOutputs: {
+ handleClick: {emit: handleClick} as any,
+ },
+ })
+ await fireEvent.click(screen.getByText(/click me/i))
+ expect(handleClick).toHaveBeenCalledTimes(1)
+})
+```
+
+
+
diff --git a/docs/dom-testing-library/api-helpers.md b/docs/dom-testing-library/api-helpers.md
deleted file mode 100644
index 6c8934c20..000000000
--- a/docs/dom-testing-library/api-helpers.md
+++ /dev/null
@@ -1,302 +0,0 @@
----
-id: api-helpers
-title: Helpers
----
-
-## 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](/docs/react-testing-library/api#render-options).
-
-## `buildQueries`
-
-The `buildQueries` helper allows you to create custom queries with all standard
-[variants](api-queries.md) of queries in testing-library.
-
-See the
-[Add custom queries](/docs/react-testing-library/setup#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 a 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')
-```
-
-
-
-```js
-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.getByText('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: [, ]
-// }
-```
-
-## 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.md#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.md b/docs/dom-testing-library/api-queries.md
deleted file mode 100644
index 72a22ba30..000000000
--- a/docs/dom-testing-library/api-queries.md
+++ /dev/null
@@ -1,748 +0,0 @@
----
-id: api-queries
-title: Queries
----
-
-## Variants
-
-> `getBy` queries are shown by default in the [query documentation](#queries)
-> below.
-
-### getBy
-
-`getBy*` queries return the first 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 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
-
-
Section One
-
some content
-
-
-// Wrapper labels
-
-
-// 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.
-
-```
-
-
-
-
-
-```javascript
-import { getByLabelText } from '@testing-library/dom'
-
-const container = document.body
-const inputNode = getByLabelText(container, 'Username')
-```
-
-
-
-```js
-import { render } from '@testing-library/react'
-
-const { getByLabelText } = render()
-
-const inputNode = getByLabelText('username')
-```
-
-
-
-```js
-cy.getByLabelText('username').should('exist')
-```
-
-
-
-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:
-
-```html
-
-```
-
-```js
-const container = document.body
-const inputNode = getByLabelText(container, 'Username', {
- selector: 'input',
-})
-```
-
-### `ByPlaceholderText`
-
-> getByPlaceholderText, queryByPlaceholderText, getAllByPlaceholderText,
-> queryAllByPlaceholderText, findByPlaceholderText, findAllByPlaceholderText
-
-```typescript
-getByPlaceholderText(
- container: HTMLElement,
- text: TextMatch,
- options?: {
- exact?: boolean = true,
- normalizer?: NormalizerFn,
- }): HTMLElement
-```
-
-This will search for all elements with a placeholder attribute and find one that
-matches the given [`TextMatch`](#textmatch).
-
-```html
-
-```
-
-
-
-
-
-```js
-import { getByPlaceholderText } from '@testing-library/dom'
-
-const container = document.body
-const inputNode = getByPlaceholderText(container, 'Username')
-```
-
-
-
-```js
-import { render } from '@testing-library/react'
-
-const { getByPlaceholderText } = render()
-const inputNode = getByPlaceholderText('Username')
-```
-
-
-
-```js
-cy.getByPlaceholderText('Username').should('exist')
-```
-
-
-
-> **Note**
->
-> A placeholder is not a good substitute for a label so you should generally use
-> `getByLabelText` instead.
-
-### `ByText`
-
-> getByText, queryByText, getAllByText, queryAllByText, findByText,
-> findAllByText
-
-```typescript
-getByText(
- container: HTMLElement,
- text: TextMatch,
- options?: {
- selector?: string = '*',
- exact?: boolean = true,
- ignore?: string|boolean = 'script, style',
- normalizer?: NormalizerFn,
- }): HTMLElement
-```
-
-This will search for all elements that have a text node with `textContent`
-matching the given [`TextMatch`](#textmatch).
-
-```html
-About ℹ️
-```
-
-
-
-
-
-```js
-import { getByText } from '@testing-library/dom'
-
-const container = document.body
-const aboutAnchorNode = getByText(container, /about/i)
-```
-
-
-
-```js
-import { render } from '@testing-library/react'
-
-const { getByText } = render()
-const aboutAnchorNode = getByText(/about/i)
-```
-
-
-
-```js
-cy.getByText(/about/i).should('exist')
-```
-
-
-
-It also works with `input`s whose `type` attribute is either `submit` or
-`button`:
-
-```js
-
-```
-
-> **Note**
->
-> See [`getByLabelText`](#bylabeltext) for more details on how and when to use
-> the `selector` option
-
-The `ignore` option accepts a query selector. If the
-[`node.matches`](https://developer.mozilla.org/en-US/docs/Web/API/Element/matches)
-returns true for that selector, the node will be ignored. This defaults to
-`'script'` because generally you don't want to select script tags, but if your
-content is in an inline script file, then the script tag could be returned.
-
-If you'd rather disable this behavior, set `ignore` to `false`.
-
-### `ByAltText`
-
-> getByAltText, queryByAltText, getAllByAltText, queryAllByAltText,
-> findByAltText, findAllByAltText
-
-```typescript
-getByAltText(
- container: HTMLElement,
- text: TextMatch,
- options?: {
- exact?: boolean = true,
- normalizer?: NormalizerFn,
- }): HTMLElement
-```
-
-This will return the element (normally an ``) that has the given `alt`
-text. Note that it only supports elements which accept an `alt` attribute:
-[``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img),
-[``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input),
-and [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/area)
-(intentionally excluding
-[`
