Skip to content

Commit 3f89381

Browse files
eps1loneps1lon
committed
Add docs for Web Testing Library
1 parent 408ed68 commit 3f89381

File tree

5 files changed

+199
-0
lines changed

5 files changed

+199
-0
lines changed

‎docs/web-testing-library/api.mdx

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
id: api
3+
title: API
4+
---
5+
6+
Several utilities are provided for dealing with asynchronous code. These can be
7+
useful to wait for an element to appear or disappear in response to an event,
8+
user action, timeout, or Promise. (See the
9+
[guide to testing disappearance](guide-disappearance.mdx).)
10+
11+
The async methods return Promises, so be sure to use `await` or `.then` when
12+
calling them.
13+
14+
## `waitFor`
15+
16+
```typescript
17+
function waitFor<T>(
18+
callback: () => T | Promise<T>,
19+
options?: {
20+
timeout?: number
21+
interval?: number
22+
onTimeout?: (error: Error) => Error
23+
},
24+
): Promise<T>
25+
```
26+
27+
When in need to wait for any period of time you can use `waitFor`, to wait for
28+
your expectations to pass. Here's a simple example:
29+
30+
```javascript
31+
// ...
32+
// Wait until the callback does not throw an error. In this case, that means
33+
// it'll wait until the mock function has been called once.
34+
await waitFor(() => expect(mockAPI).toHaveBeenCalledTimes(1))
35+
// ...
36+
```
37+
38+
`waitFor` may run the callback a number of times until the timeout is reached.
39+
Note that the number of calls is constrained by the `timeout` and `interval`
40+
options.
41+
42+
This can be useful if you have a unit test that mocks API calls and you need to
43+
wait for your mock promises to all resolve.
44+
45+
If you return a promise in the `waitFor` callback (either explicitly or
46+
implicitly with `async` syntax), then the `waitFor` utility will not call your
47+
callback again until that promise rejects. This allows you to `waitFor` things
48+
that must be checked asynchronously.
49+
50+
The default `interval` is `50ms`. However it will run your callback immediately
51+
before starting the intervals.
52+
53+
The default `timeout` is `1000ms`.
54+
55+
The default `onTimeout` takes the error and appends the `container`'s printed
56+
state to the error message which should hopefully make it easier to track down
57+
what caused the timeout.

‎docs/web-testing-library/faq.mdx

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
id: faq
3+
title: FAQ
4+
---
5+
6+
<details>
7+
8+
<summary>Why "Web" in "Web Testing Library</summary>
9+
10+
This library implements testing utilities that are used on different clients
11+
implementing the
12+
[Minimum Common Web Platform API](https://proposal-common-min-api.deno.dev/) (or
13+
parts of it). This includes browsers, Node.js, Deno and React Native.
14+
15+
React Native is included for pragmatic reasons. In the future, we might split
16+
the utilities up in Web and Timer testing utilities.
17+
18+
</details>

‎docs/web-testing-library/install.mdx

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
id: install
3+
title: Install
4+
sidebar_label: Install
5+
---
6+
7+
This module is distributed via [npm][npm] and should be installed as one of your
8+
project's `devDependencies`:
9+
10+
```
11+
npm install --save-dev @testing-library/web
12+
```
13+
14+
## Wrappers
15+
16+
If you are using a framework or library such as React, you will likely want to
17+
install the wrapper:
18+
19+
- [React Testing Library](react-testing-library/intro.mdx)
20+
- [Reason Testing Library](bs-react-testing-library/intro.mdx)
21+
- [React Native Testing Library](react-native-testing-library/intro.mdx)
22+
- [Vue Testing Library](vue-testing-library/intro.mdx)
23+
- [Marko Testing Library](marko-testing-library/intro.mdx)
24+
- [Angular Testing Library](angular-testing-library/intro.mdx)
25+
- [Preact Testing Library](preact-testing-library/intro.mdx)
26+
- [Svelte Testing Library](svelte-testing-library/intro.mdx)
27+
- [Cypress Testing Library](cypress-testing-library/intro.mdx)
28+
- [Puppeteer Testing Library](pptr-testing-library/intro.mdx)
29+
- [Testcafe Testing Library](testcafe-testing-library/intro.mdx)
30+
- [Nightwatch Testing Library](nightwatch-testing-library/intro.mdx)
31+
32+
## Ecosystem
33+
34+
`Web Testing Library` works well with these companion libraries:
35+
36+
- [user-event](user-event/intro.mdx) browser event simulation
37+
- [jest-dom](ecosystem-jest-dom.mdx) custom Jest matchers
38+
- [bs-jest-dom](ecosystem-bs-jest-dom.mdx) companion library for
39+
`bs-react-testing-library`
40+
- [jest-native](ecosystem-jest-native.mdx) companion library for
41+
`React Native Testing Library`
42+
- [react-select-event](ecosystem-react-select-event.mdx) companion library for
43+
`React Testing Library`
44+
- [eslint-plugin-testing-library](ecosystem-eslint-plugin-testing-library.mdx)
45+
ESLint plugin for Testing Library
46+
- [eslint-plugin-jest-dom](ecosystem-eslint-plugin-jest-dom.mdx) ESLint plugin
47+
for Jest DOM
48+
- [riot-testing-library](ecosystem-riot-testing-library.mdx) adds APIs for
49+
working with Riot.js components
50+
51+
## Main Exports
52+
53+
You can
54+
[review the `Web Testing Library` package.json here](https://unpkg.com/@testing-library/web/package.json).
55+
56+
In particular, the `main`, `module`, and `umd:main` fields are useful. Each of
57+
these points to a file that's useful in certain situations. Typically, your
58+
testing framework will resolve to the correct one for your situation, but if it
59+
does not, then you can either configure your testing framework to resolve to the
60+
right file when you require/import `@testing-library/dom` or you can import the
61+
file you need more explicitly. For example:
62+
63+
```js
64+
import {waitFor} from '@testing-library/web/dist/@testing-library/web.umd.js'
65+
```
66+
67+
You can
68+
[review the published `dist` files here](https://unpkg.com/@testing-library/web/dist/).
69+
70+
The `main` file is configured to compile down to support the version of node
71+
that is referenced in the `package.json` `engines.node` field. But the `module`
72+
and `umd:main` files are configured to compile down to support browsers as old
73+
as IE 10.
74+
75+
<!--
76+
Links
77+
-->
78+
79+
[npm]: https://www.npmjs.com/
80+
[node]: https://nodejs.org

‎docs/web-testing-library/intro.mdx

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
id: intro
3+
title: Introduction
4+
---
5+
6+
## The problem
7+
8+
You want to write maintainable tests for the
9+
[Web Platform](https://proposal-common-min-api.deno.dev/) or React Native. As a
10+
part of this goal, you want your tests to avoid including implementation details
11+
of your components and rather focus on making your tests give you the confidence
12+
for which they are intended. As part of this, you want your testbase to be
13+
maintainable in the long run so refactors of your components (changes to
14+
implementation but not functionality) don't break your tests and slow you and
15+
your team down.
16+
17+
## This solution
18+
19+
The `Web Testing Library` is a very light-weight solution for testing code that
20+
runs on the Web Platform (a browser, [Node.js][node], [Deno](https://deno.land/)
21+
etc) or React Native. The main utilities it provides involve querying the DOM
22+
for nodes in a way that's similar to how the user finds elements on the page. In
23+
this way, the library helps ensure your tests give you confidence in your UI
24+
code. The `DOM Testing Library`'s primary guiding principle is:
25+
26+
> [The more your tests resemble the way your software is used, the more
27+
> confidence they can give you.][guiding-principle]
28+
29+
**What this library is not**:
30+
31+
1. A test runner or framework
32+
2. Specific to a testing framework (though we do have better defaults for Jest
33+
like support for fake timers).
34+
35+
[jest]: https://jestjs.io
36+
[node]: https://nodejs.org/en/

‎sidebars.js

+8
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,14 @@ module.exports = {
162162
'svelte-testing-library/api',
163163
],
164164
},
165+
{
166+
'Web Testing Library': [
167+
'web-testing-library/intro',
168+
'web-testing-library/install',
169+
'web-testing-library/api',
170+
'web-testing-library/faq',
171+
],
172+
},
165173
'cypress-testing-library/intro',
166174
'pptr-testing-library/intro',
167175
'testcafe-testing-library/intro',

0 commit comments

Comments
 (0)