Add docs for Web Testing Library

docs/web-testing-library/api.mdx

@@ -0,0 +1,57 @@
+---
+id: api
+title: API
+---
+
+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.
+
+## `waitFor`
+
+```typescript
+function waitFor<T>(
+  callback: () => T | Promise<T>,
+  options?: {
+    timeout?: number
+    interval?: number
+    onTimeout?: (error: Error) => Error
+  },
+): Promise<T>
+```
+
+When in need to wait for any period of time you can use `waitFor`, to wait for
+your expectations to pass. 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 `async` syntax), then the `waitFor` utility will not call your
+callback again until that promise rejects. This allows you to `waitFor` things
+that must be checked asynchronously.
+
+The default `interval` is `50ms`. However it will run 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.

docs/web-testing-library/faq.mdx

@@ -0,0 +1,18 @@
+---
+id: faq
+title: FAQ
+---
+
+<details>
+
+<summary>Why "Web" in "Web Testing Library</summary>
+
+This library implements testing utilities that are used on different clients
+implementing the
+[Minimum Common Web Platform API](https://proposal-common-min-api.deno.dev/) (or
+parts of it). This includes browsers, Node.js, Deno and React Native.
+
+React Native is included for pragmatic reasons. In the future, we might split
+the utilities up in Web and Timer testing utilities.
+
+</details>

docs/web-testing-library/install.mdx

@@ -0,0 +1,80 @@
+---
+id: install
+title: Install
+sidebar_label: Install
+---
+
+This module is distributed via [npm][npm] and should be installed as one of your
+project's `devDependencies`:
+
+```
+npm install --save-dev @testing-library/web
+```
+
+## Wrappers
+
+If you are using a framework or library such as React, you will likely want to
+install the wrapper:
+
+- [React Testing Library](react-testing-library/intro.mdx)
+- [Reason Testing Library](bs-react-testing-library/intro.mdx)
+- [React Native Testing Library](react-native-testing-library/intro.mdx)
+- [Vue Testing Library](vue-testing-library/intro.mdx)
+- [Marko Testing Library](marko-testing-library/intro.mdx)
+- [Angular Testing Library](angular-testing-library/intro.mdx)
+- [Preact Testing Library](preact-testing-library/intro.mdx)
+- [Svelte Testing Library](svelte-testing-library/intro.mdx)
+- [Cypress Testing Library](cypress-testing-library/intro.mdx)
+- [Puppeteer Testing Library](pptr-testing-library/intro.mdx)
+- [Testcafe Testing Library](testcafe-testing-library/intro.mdx)
+- [Nightwatch Testing Library](nightwatch-testing-library/intro.mdx)
+
+## Ecosystem
+
+`Web Testing Library` works well with these companion libraries:
+
+- [user-event](user-event/intro.mdx) browser event simulation
+- [jest-dom](ecosystem-jest-dom.mdx) custom Jest matchers
+- [bs-jest-dom](ecosystem-bs-jest-dom.mdx) companion library for
+  `bs-react-testing-library`
+- [jest-native](ecosystem-jest-native.mdx) companion library for
+  `React Native Testing Library`
+- [react-select-event](ecosystem-react-select-event.mdx) companion library for
+  `React Testing Library`
+- [eslint-plugin-testing-library](ecosystem-eslint-plugin-testing-library.mdx)
+  ESLint plugin for Testing Library
+- [eslint-plugin-jest-dom](ecosystem-eslint-plugin-jest-dom.mdx) ESLint plugin
+  for Jest DOM
+- [riot-testing-library](ecosystem-riot-testing-library.mdx) adds APIs for
+  working with Riot.js components
+
+## Main Exports
+
+You can
+[review the `Web Testing Library` package.json here](https://unpkg.com/@testing-library/web/package.json).
+
+In particular, the `main`, `module`, and `umd:main` fields are useful. Each of
+these points to a file that's useful in certain situations. Typically, your
+testing framework will resolve to the correct one for your situation, but if it
+does not, then you can either configure your testing framework to resolve to the
+right file when you require/import `@testing-library/dom` or you can import the
+file you need more explicitly. For example:
+
+```js
+import {waitFor} from '@testing-library/web/dist/@testing-library/web.umd.js'
+```
+
+You can
+[review the published `dist` files here](https://unpkg.com/@testing-library/web/dist/).
+
+The `main` file is configured to compile down to support the version of node
+that is referenced in the `package.json` `engines.node` field. But the `module`
+and `umd:main` files are configured to compile down to support browsers as old
+as IE 10.
+
+<!--
+Links
+-->
+
+[npm]: https://www.npmjs.com/
+[node]: https://nodejs.org

docs/web-testing-library/intro.mdx

@@ -0,0 +1,49 @@
+---
+id: intro
+title: Introduction
+---
+
+## The problem
+
+You want to write maintainable tests for the
+[Web Platform](https://proposal-common-min-api.deno.dev/) or React Native. As a
+part of this goal, you want your tests to avoid including implementation details
+of your components and rather focus on making your tests give you the confidence
+for which they are intended. As part of this, you want your testbase to be
+maintainable in the long run so refactors of your components (changes to
+implementation but not functionality) don't break your tests and slow you and
+your team down.
+
+## This solution
+
+The `Web Testing Library` is a very light-weight solution for testing code that
+runs on the Web Platform (a browser, [Node.js][node], [Deno](https://deno.land/)
+etc) or React Native. The main utilities it provides involve querying the DOM
+for nodes in a way that's similar to how the user finds elements on the page. In
+this way, the library helps ensure your tests give you confidence in your UI
+code. The `DOM Testing Library`'s primary guiding principle is:
+
+> The more your tests resemble the way your software is used, the more
+> confidence they can give you.
+
+We try to only expose methods and utilities that encourage you to write tests
+that closely resemble how your code is used on the Web Platform or React Native.
+
+Utilities are included in this project based on the following guiding
+principles:
+
+1. They should be usable on both the Web Platform **and** React Native
+2. It should be generally useful for testing the application in the way the user
+   would use it. We _are_ making some trade-offs here because we're using a
+   computer and often a simulated environment, but in general, utilities should
+   encourage tests that use the application the way they're intended to be used.
+3. Utility implementations and APIs should be simple and flexible.
+
+**What this library is not**:
+
+1.  A test runner or framework
+2.  Specific to a testing framework (though we do have better defaults for Jest
+    like support for fake timers).
+
+[jest]: https://jestjs.io
+[node]: https://nodejs.org/en/

sidebars.js

@@ -162,6 +162,14 @@ module.exports = {
             'svelte-testing-library/api',
           ],
         },
+        {
+          'Web Testing Library': [
+            'web-testing-library/intro',
+            'web-testing-library/install',
+            'web-testing-library/api',
+            'web-testing-library/faq',
+          ],
+        },
         'cypress-testing-library/intro',
         'pptr-testing-library/intro',
         'testcafe-testing-library/intro',