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 2a1e448

Browse files
joshuaellismpeyper
andauthored
docs: add renderer and SSR documentation
Co-authored-by: Michael Peyper <mpeyper7@gmail.com>
1 parent dc21e59 commit 2a1e448

File tree

6 files changed

+300
-69
lines changed

6 files changed

+300
-69
lines changed

‎README.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@
4242
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4343
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
4444

45+
4546
- [The problem](#the-problem)
4647
- [The solution](#the-solution)
4748
- [When to use this library](#when-to-use-this-library)
@@ -141,17 +142,22 @@ npm install --save-dev @testing-library/react-hooks
141142
### Peer Dependencies
142143

143144
`react-hooks-testing-library` does not come bundled with a version of
144-
[`react`](https://www.npmjs.com/package/react) or
145-
[`react-test-renderer`](https://www.npmjs.com/package/react-test-renderer) to allow you to install
146-
the specific version you want to test against. Generally, the installed versions for `react` and
147-
`react-test-renderer` should have matching versions:
145+
[`react`](https://www.npmjs.com/package/react) to allow you to install the specific version you want
146+
to test against. It also does not come installed with a specific renderer, we currently support
147+
[`react-test-renderer`](https://www.npmjs.com/package/react-test-renderer) and
148+
[`react-dom`](https://www.npmjs.com/package/react-dom). You only need to install one of them,
149+
however, if you do have both installed, we will use `react-test-renderer` as the default. For more
150+
information see the [installation docs](https://react-hooks-testing-library.com/#installation).
151+
Generally, the installed versions for `react` and the selected renderer should have matching
152+
versions:
148153

149154
```sh
150155
npm install react@^16.9.0
151156
npm install --save-dev react-test-renderer@^16.9.0
152157
```
153158

154-
> **NOTE: The minimum supported version of `react` and `react-test-renderer` is `^16.9.0`.**
159+
> **NOTE: The minimum supported version of `react`, `react-test-renderer` and `react-dom` is
160+
> `^16.9.0`.**
155161
156162
## API
157163

‎docs/api-reference.md

Lines changed: 50 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,14 @@ route: '/reference/api'
1111
- [`act`](/reference/api#act)
1212
- [`cleanup`](/reference/api#cleanup)
1313
- [`addCleanup`](/reference/api#addcleanup)
14+
- [`removeCleanup`](/reference/api#removecleanup)
1415

1516
---
1617

1718
## `renderHook`
1819

19-
```js
20-
function renderHook(
21-
callback: function(props?: any): any,
22-
options?: RenderHookOptions
23-
): RenderHookResult
20+
```ts
21+
function renderHook(callback: (props?: any) => any, options?: RenderHookOptions): RenderHookResult
2422
```
2523

2624
Renders a test component that will call the provided `callback`, including any hooks it calls, every
@@ -61,7 +59,7 @@ The `renderHook` function returns an object that has the following properties:
6159

6260
### `result`
6361

64-
```js
62+
```ts
6563
{
6664
all: Array<any>
6765
current: any,
@@ -77,7 +75,7 @@ returned at the time.
7775

7876
### `rerender`
7977

80-
```js
78+
```ts
8179
function rerender(newProps?: any): void
8280
```
8381

@@ -86,13 +84,27 @@ passed, they will replace the `callback` function's `initialProps` for subsequen
8684

8785
### `unmount`
8886

89-
```js
87+
```ts
9088
function unmount(): void
9189
```
9290

9391
A function to unmount the test component. This is commonly used to trigger cleanup effects for
9492
`useEffect` hooks.
9593

94+
### `hydrate`
95+
96+
```ts
97+
function hydrate(): void
98+
```
99+
100+
> This is only used when using the `server` module. See [SSR](/usage/ssr) for more information on
101+
> server-side rendering your hooks.
102+
103+
A function to hydrate a server rendered component into the DOM. This is required before you can
104+
interact with the hook, whether that is an `act` or `rerender` call. Effects created using
105+
`useEffect` or `useLayoutEffect` are also not run on server rendered hooks until `hydrate` is
106+
called.
107+
96108
### `...asyncUtils`
97109

98110
Utilities to assist with testing asynchronous behaviour. See the
@@ -102,15 +114,15 @@ Utilities to assist with testing asynchronous behaviour. See the
102114

103115
## `act`
104116

105-
This is the same [`act` function](https://reactjs.org/docs/test-utils.html#act) that is exported by
106-
`react-test-renderer`.
117+
This is the same [`act` function](https://reactjs.org/docs/test-utils.html#act) function that is
118+
exportedfromyour [chosenrenderer](/installation#renderer).
107119

108120
---
109121

110122
## `cleanup`
111123

112-
```js
113-
function cleanup: Promise<void>
124+
```ts
125+
function cleanup(): Promise<void>
114126
```
115127

116128
Unmounts any rendered hooks rendered with `renderHook`, ensuring all effects have been flushed. Any
@@ -142,7 +154,8 @@ module.exports = {
142154
```
143155

144156
Alternatively, you can change your test to import from `@testing-library/react-hooks/pure` instead
145-
of the regular imports.
157+
of the regular imports. This applys to any of our export methods documented in
158+
[Rendering](/installation#being-specific).
146159

147160
```diff
148161
- import { renderHook, cleanup, act } from '@testing-library/react-hooks'
@@ -156,8 +169,8 @@ variable to `true` before importing `@testing-library/react-hooks` will also dis
156169

157170
## `addCleanup`
158171

159-
```js
160-
function addCleanup(callback: function(): void|Promise<void>): function(): void
172+
```ts
173+
function addCleanup(callback: () => void | Promise<void>): (): void
161174
```
162175

163176
Add a callback to be called during [`cleanup`](/reference/api#cleanup), returning a function to
@@ -173,8 +186,8 @@ be resolved before moving onto the next cleanup callback.
173186

174187
## `removeCleanup`
175188

176-
```js
177-
function removeCleanup(callback: function(): void|Promise<void>): void
189+
```ts
190+
function removeCleanup(callback: () =>void|Promise<void>): void
178191
```
179192

180193
Removes a cleanup callback previously added with [`addCleanup`](/reference/api#addCleanup). Once
@@ -187,10 +200,8 @@ removed, the provided callback will no longer execute as part of running
187200

188201
### `waitForNextUpdate`
189202

190-
```js
191-
function waitForNextUpdate(options?: {
192-
timeout?: number
193-
}): Promise<void>
203+
```ts
204+
function waitForNextUpdate(options?: { timeout?: number }): Promise<void>
194205
```
195206

196207
Returns a `Promise` that resolves the next time the hook renders, commonly when state is updated as
@@ -202,12 +213,15 @@ The maximum amount of time in milliseconds (ms) to wait. By default, no timeout
202213

203214
### `waitFor`
204215

205-
```js
206-
function waitFor(callback: function(): boolean|void, options?: {
207-
interval?: number,
208-
timeout?: number,
209-
suppressErrors?: boolean
210-
}): Promise<void>
216+
```ts
217+
function waitFor(
218+
callback: () => boolean | void,
219+
options?: {
220+
interval?: number
221+
timeout?: number
222+
suppressErrors?: boolean
223+
}
224+
): Promise<void>
211225
```
212226

213227
Returns a `Promise` that resolves if the provided callback executes without exception and returns a
@@ -232,12 +246,15 @@ rejected. By default, errors are suppressed for this utility.
232246

233247
### `waitForValueToChange`
234248

235-
```js
236-
function waitForValueToChange(selector: function(): any, options?: {
237-
interval?: number,
238-
timeout?: number,
239-
suppressErrors?: boolean
240-
}): Promise<void>
249+
```ts
250+
function waitForValueToChange(
251+
selector: () => any,
252+
options?: {
253+
interval?: number
254+
timeout?: number
255+
suppressErrors?: boolean
256+
}
257+
): Promise<void>
241258
```
242259

243260
Returns a `Promise` that resolves if the value returned from the provided selector changes. It is

‎docs/installation.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
name: Installation
3+
route: '/installation'
4+
---
5+
6+
# Installation
7+
8+
## Getting started
9+
10+
This module is distributed via [npm](https://www.npmjs.com/) which is bundled with
11+
[node](https://nodejs.org) and should be installed as one of your project's `devDependencies`:
12+
13+
```sh
14+
# if you're using npm
15+
npm install --save-dev @testing-library/react-hooks
16+
# if you're using yarn
17+
yarn add --dev @testing-library/react-hooks
18+
```
19+
20+
### Peer Dependencies
21+
22+
`react-hooks-testing-library` does not come bundled with a version of
23+
[`react`](https://www.npmjs.com/package/react) to allow you to install the specific version you want
24+
to test against. It also does not come installed with a specific renderer, we currently support
25+
[`react-test-renderer`](https://www.npmjs.com/package/react-test-renderer) and
26+
[`react-dom`](https://www.npmjs.com/package/react-dom), you only need to install one of them. For
27+
more information see [Renderer](/installation#renderer)
28+
29+
```sh
30+
npm install react@^16.9.0
31+
npm install --save-dev react-test-renderer@^16.9.0
32+
```
33+
34+
> **NOTE: The minimum supported version of `react`, `react-test-renderer` and `react-dom` is
35+
> `^16.9.0`.**
36+
37+
## Renderer
38+
39+
When running tests, a renderer is required in order to render the React component we wrap around
40+
your hook. We currently support two different renderers:
41+
42+
- `react-test-renderer`
43+
- `react-dom`
44+
45+
When using standard import for this library (show below), we will attempt to auto-detect which
46+
renderer you have installed and use it without needing any specific wiring up to make it happen. If
47+
you have both installed in your project, and you use the standard import (see below) the library
48+
will default to using `react-test-renderer`.
49+
50+
> We use `react-test-renderer` by default as it enables hooks to be tested that are designed for
51+
> either `react` or `react-native` and it is compatible with more test runners out-of-the-box as
52+
> there is no DOM requirement to use it.
53+
54+
The standard import looks like:
55+
56+
```js
57+
import { renderHook } from '@testing-library/react-hooks'
58+
```
59+
60+
> Note: The auto detection function may not work if tests are bundles before execution (e.g. to be
61+
> run in a browser)
62+
63+
### Act
64+
65+
Each render also provides a unique [`act` function](https://reactjs.org/docs/test-utils.html#act)
66+
that cannot be used with other renderers. In order to simplify with `act `function you need to use,
67+
we also export the correct one alongside the detected renderer for you:
68+
69+
```js
70+
import { renderHook, act } from '@testing-library/react-hooks'
71+
```
72+
73+
## Being specific
74+
75+
Auto-detection is great for simplifying setup and getting out of your way, but sometimes you do need
76+
a little but more control. If a test needs requires a specific type of environment, the import can
77+
be appended to force a specific renderer to be use. The supported environments are:
78+
79+
- `dom`
80+
- `native`
81+
- `server`
82+
83+
The imports for each type of renderer are as follows:
84+
85+
```ts
86+
import { renderHook, act } from '@testing-library/react-hooks' // will attempt to auto-detect
87+
88+
import { renderHook, act } from '@testing-library/react-hooks/dom' // will use react-dom
89+
90+
import { renderHook, act } from '@testing-library/react-hooks/native' // will use react-test-renderer
91+
92+
import { renderHook, act } from '@testing-library/react-hooks/server' // will use react-dom/server
93+
```
94+
95+
## Testing Framework
96+
97+
In order to run tests, you will probably want to be using a test framework. If you have not already
98+
got one, we recommend using [Jest](https://jestjs.io/), but this library should work without issues
99+
with any of the alternatives.

‎docs/introduction.md

Lines changed: 0 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -55,33 +55,3 @@ the results.
5555

5656
1. Your hook is defined alongside a component and is only used there
5757
2. Your hook is easy to test by just testing the components using it
58-
59-
## Installation
60-
61-
This module is distributed via [npm](https://www.npmjs.com/) which is bundled with
62-
[node](https://nodejs.org) and should be installed as one of your project's `devDependencies`:
63-
64-
```sh
65-
npm install --save-dev @testing-library/react-hooks
66-
```
67-
68-
### Peer Dependencies
69-
70-
`react-hooks-testing-library` does not come bundled with a version of
71-
[`react`](https://www.npmjs.com/package/react) or
72-
[`react-test-renderer`](https://www.npmjs.com/package/react-test-renderer) to allow you to install
73-
the specific version you want to test against. Generally, the installed versions for `react` and
74-
`react-test-renderer` should have matching versions:
75-
76-
```sh
77-
npm install react@^16.9.0
78-
npm install --save-dev react-test-renderer@^16.9.0
79-
```
80-
81-
> **NOTE: The minimum supported version of `react` and `react-test-renderer` is `^16.9.0`.**
82-
83-
## Testing Framework
84-
85-
In order to run tests, you will probably want to be using a test framework. If you have not already
86-
got one, we recommend using [Jest](https://jestjs.io/), but this library should work without issues
87-
with any of the alternatives.

0 commit comments

Comments
(0)

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