Skip to content

Commit 698579c

Browse files
committed
docs: update docs to with more detail on side effects
1 parent e7cce51 commit 698579c

File tree

2 files changed

+35
-12
lines changed

2 files changed

+35
-12
lines changed

docs/api-reference.md

+9-10
Original file line numberDiff line numberDiff line change
@@ -154,9 +154,8 @@ module.exports = {
154154
}
155155
```
156156

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

161160
```diff
162161
- import { renderHook, cleanup, act } from '@testing-library/react-hooks'
@@ -282,10 +281,11 @@ used to wrap the hook call includes an
282281
[significant amount of output noise](https://reactjs.org/docs/error-boundaries.html#component-stack-traces)
283282
in tests.
284283

285-
To keep test output clean, we patch `console.error` when `renderHook` is called to filter out the
286-
unnecessary logging and restore the original version during cleanup. This side-effect can affect
287-
tests that also patch `console.error` (e.g. to assert a specific error message get logged) by
288-
replacing their custom implementation as well.
284+
To keep test output clean, we patch `console.error` when importing from
285+
`@testing-library/react-hooks` (or any of the [other non-pure imports](/installation#pure-imports))
286+
to filter out the unnecessary logging and restore the original version during cleanup. This
287+
side-effect can affect tests that also patch `console.error` (e.g. to assert a specific error
288+
message get logged) by replacing their custom implementation as well.
289289

290290
### Disabling `console.error` filtering
291291

@@ -304,9 +304,8 @@ module.exports = {
304304
}
305305
```
306306

307-
Alternatively, you can change your test to import from `@testing-library/react-hooks/pure` instead
308-
of the regular imports. This applies to any of our export methods documented in
309-
[Rendering](/installation#being-specific).
307+
Alternatively, you can change your test to import from `@testing-library/react-hooks/pure` (or any
308+
of the [other non-pure imports](/installation#pure-imports)) instead of the regular imports.
310309

311310
```diff
312311
- import { renderHook, cleanup, act } from '@testing-library/react-hooks'

docs/installation.md

+26-2
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ npm install --save-dev @testing-library/react-hooks
1717
yarn add --dev @testing-library/react-hooks
1818
```
1919

20-
### Peer Dependencies
20+
### Peer dependencies
2121

2222
`react-hooks-testing-library` does not come bundled with a version of
2323
[`react`](https://www.npmjs.com/package/react) to allow you to install the specific version you want
@@ -92,7 +92,31 @@ import { renderHook, act } from '@testing-library/react-hooks/native' // will us
9292
import { renderHook, act } from '@testing-library/react-hooks/server' // will use react-dom/server
9393
```
9494
95-
## Testing Framework
95+
## Pure imports
96+
97+
Importing from any of the previously mentioned imports will cause some side effects in the test
98+
environment:
99+
100+
1. `cleanup` is automatically called in an `afterEach` block
101+
2. `console.error` is patched to hide some React errors
102+
103+
The specifics of these side effects are discussed in more detail in the
104+
[API reference](/reference/api).
105+
106+
If you want to ensure the imports are free of side-effects, you can use the `pure` imports instead,
107+
which can be accessed by appending `/pure` to the end of any of the other imports:
108+
109+
```ts
110+
import { renderHook, act } from '@testing-library/react-hooks/pure'
111+
112+
import { renderHook, act } from '@testing-library/react-hooks/dom/pure'
113+
114+
import { renderHook, act } from '@testing-library/react-hooks/native/pure'
115+
116+
import { renderHook, act } from '@testing-library/react-hooks/server/pure'
117+
```
118+
119+
## Testing framework
96120

97121
In order to run tests, you will probably want to be using a test framework. If you have not already
98122
got one, we recommend using [Jest](https://jestjs.io/), but this library should work without issues

0 commit comments

Comments
 (0)