Skip to content

Commit c88c743

Browse files
joshuaellismpeyper
andauthored
docs: update with suggestions
Co-authored-by: Michael Peyper <mpeyper7@gmail.com>
1 parent 05dad4f commit c88c743

File tree

1 file changed

+33
-15
lines changed

1 file changed

+33
-15
lines changed

docs/installation.md

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,42 +36,60 @@ npm install --save-dev react-test-renderer@^16.9.0
3636
3737
## Renderer
3838

39-
React requires a rendering engine, typically when creating an application people use `react-dom`.
40-
When running tests, React still requires an engine. We currently support two different engines:
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:
4141

4242
- `react-test-renderer`
4343
- `react-dom`
4444

45-
If you have both installed in your project, assuming you're using the default imports (see below)
46-
the library defaults to using `react-test-renderer`. This is because rtr is the defacto test
47-
renderer for `react-native` for tests and it enables hooks to be correctly tested that are written
48-
for both `react` & `react-native`.
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:
4955

5056
```js
5157
import { renderHook } from '@testing-library/react-hooks'
5258
```
5359

54-
> The auto detection function may not work if tests are bundled to run in the browser.
60+
> Note: The auto detection function may not work if tests are bundles before execution (e.g. to be
61+
> run in a browser)
5562
56-
## Being specific
63+
### Act
5764

58-
If, however, for certain tests you want to use a specific renderer (e.g. you want to use `react-dom`
59-
for SSR) you can import the server module directly:
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:
6068

61-
```ts
62-
import { renderHook } from '@testing-library/react-hooks/server`
69+
```js
70+
import { renderHook, act } from '@testing-library/react-hooks'
6371
```
6472

65-
We have the following exports available:
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:
6684

6785
```ts
68-
import { renderHook, act } from '@testing-library/react-hooks' // will try to auto-detect
86+
import { renderHook, act } from '@testing-library/react-hooks' // will attempt to auto-detect
6987
7088
import { renderHook, act } from '@testing-library/react-hooks/dom' // will use react-dom
7189
7290
import { renderHook, act } from '@testing-library/react-hooks/native' // will use react-test-renderer
7391
74-
import { renderHook, act } from '@testing-library/react-hooks/server' // will use react-dom
92+
import { renderHook, act } from '@testing-library/react-hooks/server' // will use react-dom/server
7593
```
7694
7795
## Testing Framework

0 commit comments

Comments
 (0)