Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 3f89381

Browse files
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

Lines changed: 57 additions & 0 deletions
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

Lines changed: 18 additions & 0 deletions
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

Lines changed: 80 additions & 0 deletions
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

Lines changed: 36 additions & 0 deletions
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

Lines changed: 8 additions & 0 deletions
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)

AltStyle によって変換されたページ (->オリジナル) /