You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/introduction/getting-started.md
+14-5
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ route: '/'
17
17
</a>
18
18
19
19
<p>
20
-
Simple component wrapper and utilities for testing React hooks.
20
+
Simple and complete React hooks testing utilities that encourage good testing practices.
21
21
</p>
22
22
23
23
</div>
@@ -26,17 +26,26 @@ route: '/'
26
26
27
27
## The problem
28
28
29
-
You're writing an awesome custom hook and you want to test it, but as soon as you call it you see the following error:
29
+
You're writing an awesome custom hook and you want to test it, but as soon as you call it you see
30
+
the following error:
30
31
31
32
> Invariant Violation: Hooks can only be called inside the body of a function component.
32
33
33
-
You don't really want to write a component solely for testing this hook and have to work out how you were going to trigger all the various ways the hook can be updated, especially given the complexities of how you've wired the whole thing together.
34
+
You don't really want to write a component solely for testing this hook and have to work out how you
35
+
were going to trigger all the various ways the hook can be updated, especially given the
36
+
complexities of how you've wired the whole thing together.
34
37
35
38
## The solution
36
39
37
-
The `react-hooks-testing-library` allows you to create a simple test harness for React hooks that handles running them within the body of a function component, as well as providing various useful utility functions for updating the inputs and retrieving the outputs of your amazing custom hook. This library aims to provide a testing experience as close as possible to natively using your hook from within a real component.
40
+
The `react-hooks-testing-library` allows you to create a simple test harness for React hooks that
41
+
handles running them within the body of a function component, as well as providing various useful
42
+
utility functions for updating the inputs and retrieving the outputs of your amazing custom hook.
43
+
This library aims to provide a testing experience as close as possible to natively using your hook
44
+
from within a real component.
38
45
39
-
Using this library, you do not have to concern yourself with how to construct, render or interact with the react component in order to test your hook. You can just use the hook directly and assert the results.
46
+
Using this library, you do not have to concern yourself with how to construct, render or interact
47
+
with the react component in order to test your hook. You can just use the hook directly and assert
In order to run tests, you will probably want to be using a test framework. If you have not already got one, we recommend using [jest](https://jestjs.io/), but this library should work without issues with any of the alternatives.
20
+
In order to run tests, you will probably want to be using a test framework. If you have not already
21
+
got one, we recommend using [jest](https://jestjs.io/), but this library should work without issues
Copy file name to clipboardExpand all lines: docs/reference/api.md
+21-14
Original file line number
Diff line number
Diff line change
@@ -22,23 +22,23 @@ function renderHook(
22
22
): RenderHookResult
23
23
```
24
24
25
-
Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders.
25
+
Renders a test component that will call the provided `callback`, including any hooks it calls, every
26
+
time it renders.
26
27
27
28
The `renderHook` function accept the following arguments:
28
29
29
30
### `callback`
30
31
31
-
The function that is called each `render` of the test component. This function should call one or more hooks for testing.
32
+
The function that is called each `render` of the test component. This function should call one or
33
+
more hooks for testing.
32
34
33
-
The `props` passed into the callback will be the `initialProps` provided in the `options` to `renderHook`, unless new props are provided by a subsequent `rerender` call.
35
+
The `props` passed into the callback will be the `initialProps` provided in the `options` to
36
+
`renderHook`, unless new props are provided by a subsequent `rerender` call.
34
37
35
38
### `options`
36
39
37
-
An options object to modify the execution of the `callback` function. See the [`renderHook` Options](/reference/api#renderhook-options) section for more details.
38
-
39
-
> _Note: `testHook` has been renamed to `renderHook`. `testHook` will continue work in the current version with a deprecation warning, but will be removed in a future version._
40
-
>
41
-
> **_You should update any usages of `testHook` to use `renderHook` instead._**
40
+
An options object to modify the execution of the `callback` function. See the
41
+
[`renderHook` Options](/reference/api#renderhook-options) section for more details.
42
42
43
43
## `renderHook` Options
44
44
@@ -50,7 +50,8 @@ The initial values to pass as `props` to the `callback` function of `renderHook.
50
50
51
51
### `wrapper`
52
52
53
-
A React component to wrap the test component in when rendering. This is usually used to add context providers from `React.createContext` for the hook to access with `useContext`.
53
+
A React component to wrap the test component in when rendering. This is usually used to add context
54
+
providers from `React.createContext` for the hook to access with `useContext`.
54
55
55
56
## `renderHook` Result
56
57
@@ -65,34 +66,40 @@ The `renderHook` method returns an object that has a following properties:
65
66
}
66
67
```
67
68
68
-
The `current` value or the `result` will reflect whatever is returned from the `callback` passed to `renderHook`. Any thrown values will be reflected in the `error` value of the `result`.
69
+
The `current` value or the `result` will reflect whatever is returned from the `callback` passed to
70
+
`renderHook`. Any thrown values will be reflected in the `error` value of the `result`.
69
71
70
72
### `waitForNextUpdate`
71
73
72
74
```js
73
75
functionwaitForNextUpdate(): Promise<void>
74
76
```
75
77
76
-
- `waitForNextUpdate` (`function`) - returns a `Promise` that resolves the next time the hook renders, commonly when state is updated as the result of a asynchronous action
78
+
- `waitForNextUpdate` (`function`) - returns a `Promise` that resolves the next time the hook
79
+
renders, commonly when state is updated as the result of a asynchronous action
77
80
78
81
### `rerender`
79
82
80
83
```js
81
84
function rerender(newProps?: any): void
82
85
```
83
86
84
-
A function to rerender the test component, causing any hooks to be recalculated. If `newProps` are passed, the will replace the `initialProps` passed to the `callback` function for the rerender any subsequent renders.
87
+
A function to rerender the test component, causing any hooks to be recalculated. If `newProps` are
88
+
passed, the will replace the `initialProps` passed to the `callback` function for the rerender any
89
+
subsequent renders.
85
90
86
91
### `unmount`
87
92
88
93
```js
89
94
function unmount(): void
90
95
```
91
96
92
-
A function to unmount the test component. This is commonly used to trigger cleanup effects for `useEffect` hooks.
97
+
A function to unmount the test component. This is commonly used to trigger cleanup effects for
98
+
`useEffect` hooks.
93
99
94
100
---
95
101
96
102
## `act`
97
103
98
-
This is the same [`act` function](https://reactjs.org/docs/test-utils.html#act) that is exported by `react-test-renderer`.
104
+
This is the same [`act` function](https://reactjs.org/docs/test-utils.html#act) that is exported by
Copy file name to clipboardExpand all lines: docs/usage/advanced-hooks.md
+41-16
Original file line number
Diff line number
Diff line change
@@ -8,9 +8,12 @@ route: '/usage/advanced-hooks'
8
8
9
9
## Context
10
10
11
-
Often, a hook is going to need a value out of context. The `useContext` hook is really good for this, but it will ofter required a `Provider` to be wrapped around the component using the hook. We can use the `wrapper` option for `renderHook` to do just that.
11
+
Often, a hook is going to need a value out of context. The `useContext` hook is really good for
12
+
this, but it will ofter required a `Provider` to be wrapped around the component using the hook. We
13
+
can use the `wrapper` option for `renderHook` to do just that.
12
14
13
-
Let's change the `useCounter` example from the [Basic Hooks section](/usage/basic-hooks) to get a `step` value from context and build a `CounterStepProvider` that allows us to set the value:
15
+
Let's change the `useCounter` example from the [Basic Hooks section](/usage/basic-hooks) to get a
16
+
`step` value from context and build a `CounterStepProvider` that allows us to set the value:
test('should use custom step when incrementing', () => {
@@ -48,20 +51,28 @@ test('should use custom step when incrementing', () => {
48
51
})
49
52
```
50
53
51
-
The `wrapper` option will accept any React component, but it **must** render `children` in order for the test component to render and the hook to execute.
54
+
The `wrapper` option will accept any React component, but it **must** render `children` in order for
55
+
the test component to render and the hook to execute.
52
56
53
57
### ESLint Warning
54
58
55
-
It can be very tempting to try to inline the `wrapper` variable into the `renderHook` line, and there is nothing technically wrong with doing that, but if you are using [`eslint`](https://eslint.org/) and [`eslint-plugin-react`](https://github.com/yannickcr/eslint-plugin-react), you will see a linting error that says:
59
+
It can be very tempting to try to inline the `wrapper` variable into the `renderHook` line, and
60
+
there is nothing technically wrong with doing that, but if you are using
61
+
[`eslint`](https://eslint.org/) and
62
+
[`eslint-plugin-react`](https://github.com/yannickcr/eslint-plugin-react), you will see a linting
63
+
error that says:
56
64
57
65
> Component definition is missing display name
58
66
59
-
This is caused by the `react/display-name` rule and although it's unlikely to cause you any issues, it's best to take steps to remove it. If you feel strongly about not having a seperate `wrapper` variable, you can disable the error for the test file but adding a special comment to the top of the file:
67
+
This is caused by the `react/display-name` rule and although it's unlikely to cause you any issues,
68
+
it's best to take steps to remove it. If you feel strongly about not having a seperate `wrapper`
69
+
variable, you can disable the error for the test file but adding a special comment to the top of the
test('should use custom step when incrementing', () => {
@@ -77,13 +88,19 @@ test('should use custom step when incrementing', () => {
77
88
})
78
89
```
79
90
80
-
Similar techniques can be used to disable the error for just the specific line, or for the whole project, but please take the time to understand the impact that disabling linting rules will have on you, your team, and your project.
91
+
Similar techniques can be used to disable the error for just the specific line, or for the whole
92
+
project, but please take the time to understand the impact that disabling linting rules will have on
93
+
you, your team, and your project.
81
94
82
95
## Async
83
96
84
-
Sometimes, a hook can trigger asynchronous updates that will not be immediately reflected in the `result.current` value. Luckily, `renderHook` returns a utility that allows the test to wait for the hook to update using `async/await` (or just promise callbacks if you prefer) called `waitForNextUpdate`.
97
+
Sometimes, a hook can trigger asynchronous updates that will not be immediately reflected in the
98
+
`result.current` value. Luckily, `renderHook` returns a utility that allows the test to wait for the
99
+
hook to update using `async/await` (or just promise callbacks if you prefer) called
100
+
`waitForNextUpdate`.
85
101
86
-
Let's further extend `useCounter` to have an `incrementAsync` callback that will update the `count` after `100ms`:
102
+
Let's further extend `useCounter` to have an `incrementAsync` callback that will update the `count`
`waitForNextUpdate` will also wait for hooks that suspends using [React's `Suspense`](https://reactjs.org/docs/code-splitting.html#suspense) functionality finish rendering.
137
+
`waitForNextUpdate` will also wait for hooks that suspends using
When testing async hooks, you will likely see a warning from React that tells you to wrap the update in `act(() => {...})`, but you can't because the update is internal to the hook code, not the test code. This is a [known issue](https://github.com/mpeyper/react-hooks-testing-library/issues/14) and should have a fix when React `v16.9.0` is released, but until then, you can either just ignore the warning, or suppress the output:
143
+
When testing async hooks, you will likely see a warning from React that tells you to wrap the update
144
+
in `act(() => {...})`, but you can't because the update is internal to the hook code, not the test
145
+
code. This is a [known issue](https://github.com/mpeyper/react-hooks-testing-library/issues/14) and
146
+
should have a fix when React `v16.9.0` is released, but until then, you can either just ignore the
If you need to test that a hook throws the errors you expect it to, you can use `result.error` to access an error that may have been thrown in the previous render. For example, we could make the `useCounter` hook threw an error if the count reached a specific value:
173
+
If you need to test that a hook throws the errors you expect it to, you can use `result.error` to
174
+
access an error that may have been thrown in the previous render. For example, we could make the
175
+
`useCounter` hook threw an error if the count reached a specific value:
0 commit comments