1 | <div align="center">
|
2 | <h1>react-hooks-testing-library</h1>
|
3 |
|
4 | <a href="https://www.emojione.com/emoji/1f40f">
|
5 | <img
|
6 | height="80"
|
7 | width="80"
|
8 | alt="ram"
|
9 | src="https://raw.githubusercontent.com/testing-library/react-hooks-testing-library/master/other/ram.png"
|
10 | />
|
11 | </a>
|
12 |
|
13 | <p>Simple and complete React hooks testing utilities that encourage good testing practices.</p>
|
14 |
|
15 | <br />
|
16 | <a href="https://react-hooks-testing-library.com/"><strong>Read The Docs</strong></a>
|
17 | <br />
|
18 | </div>
|
19 |
|
20 | <hr />
|
21 |
|
22 |
|
23 |
|
24 | [![Build Status](https://img.shields.io/travis/testing-library/react-hooks-testing-library.svg?style=flat-square)](https://travis-ci.org/testing-library/react-hooks-testing-library)
|
25 | [![codecov](https://img.shields.io/codecov/c/github/testing-library/react-hooks-testing-library.svg?style=flat-square)](https://codecov.io/gh/testing-library/react-hooks-testing-library)
|
26 | [![version](https://img.shields.io/npm/v/@testing-library/react-hooks.svg?style=flat-square)](https://www.npmjs.com/package/@testing-library/react-hooks)
|
27 | [![downloads](https://img.shields.io/npm/dm/@testing-library/react-hooks.svg?style=flat-square)](http://www.npmtrends.com/@testing-library/react-hooks)
|
28 | [![MIT License](https://img.shields.io/npm/l/@testing-library/react-hooks.svg?style=flat-square)](https://github.com/testing-library/react-hooks-testing-library/blob/master/LICENSE.md)
|
29 |
|
30 | [![All Contributors](https://img.shields.io/badge/all_contributors-13-orange.svg?style=flat-square)](#contributors)
|
31 | [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
|
32 | [![Code of Conduct](https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square)](https://github.com/testing-library/react-hooks-testing-library/blob/master/CODE_OF_CONDUCT.md)
|
33 | [![Netlify Status](https://api.netlify.com/api/v1/badges/9a8f27a5-df38-4910-a248-4908b1ba29a7/deploy-status)](https://app.netlify.com/sites/react-hooks-testing-library/deploys)
|
34 |
|
35 | [![Watch on GitHub](https://img.shields.io/github/watchers/testing-library/react-hooks-testing-library.svg?style=social)](https://github.com/testing-library/react-hooks-testing-library/watchers)
|
36 | [![Star on GitHub](https://img.shields.io/github/stars/testing-library/react-hooks-testing-library.svg?style=social)](https://github.com/testing-library/react-hooks-testing-library/stargazers)
|
37 | [![Tweet](https://img.shields.io/twitter/url/https/github.com/testing-library/react-hooks-testing-library.svg?style=social)](https://twitter.com/intent/tweet?text=Check%20out%20react-hooks-testing-library%20by%20%40testing-library%20https%3A%2F%2Fgithub.com%2Ftesting-library%2Freact-hooks-testing-library%20%F0%9F%91%8D)
|
38 |
|
39 | ## The problem
|
40 |
|
41 | You're writing an awesome custom hook and you want to test it, but as soon as you call it you see
|
42 | the following error:
|
43 |
|
44 | > Invariant Violation: Hooks can only be called inside the body of a function component.
|
45 |
|
46 | You don't really want to write a component solely for testing this hook and have to work out how you
|
47 | were going to trigger all the various ways the hook can be updated, especially given the
|
48 | complexities of how you've wired the whole thing together.
|
49 |
|
50 | ## The solution
|
51 |
|
52 | The `react-hooks-testing-library` allows you to create a simple test harness for React hooks that
|
53 | handles running them within the body of a function component, as well as providing various useful
|
54 | utility functions for updating the inputs and retrieving the outputs of your amazing custom hook.
|
55 | This library aims to provide a testing experience as close as possible to natively using your hook
|
56 | from within a real component.
|
57 |
|
58 | Using this library, you do not have to concern yourself with how to construct, render or interact
|
59 | with the react component in order to test your hook. You can just use the hook directly and assert
|
60 | the results.
|
61 |
|
62 | ## When to use this library
|
63 |
|
64 | 1. You're writing a library with one or more custom hooks that are not directly tied to a component
|
65 | 2. You have a complex hook that is difficult to test through component interactions
|
66 |
|
67 | ## When not to use this library
|
68 |
|
69 | 1. Your hook is defined alongside a component and is only used there
|
70 | 2. Your hook is easy to test by just testing the components using it
|
71 |
|
72 | ## Example
|
73 |
|
74 | ### `useCounter.js`
|
75 |
|
76 | ```js
|
77 | import { useState, useCallback } from 'react'
|
78 |
|
79 | function useCounter() {
|
80 | const [count, setCount] = useState(0)
|
81 |
|
82 | const increment = useCallback(() => setCount((x) => x + 1), [])
|
83 |
|
84 | return { count, increment }
|
85 | }
|
86 |
|
87 | export default useCounter
|
88 | ```
|
89 |
|
90 | ### `useCounter.test.js`
|
91 |
|
92 | ```js
|
93 | import { renderHook, act } from '@testing-library/react-hooks'
|
94 | import useCounter from './useCounter'
|
95 |
|
96 | test('should increment counter', () => {
|
97 | const { result } = renderHook(() => useCounter())
|
98 |
|
99 | act(() => {
|
100 | result.current.increment()
|
101 | })
|
102 |
|
103 | expect(result.current.count).toBe(1)
|
104 | })
|
105 | ```
|
106 |
|
107 | More advanced usage can be found in the
|
108 | [documentation](https://react-hooks-testing-library.com/usage/basic-hooks).
|
109 |
|
110 | ## Installation
|
111 |
|
112 | ```sh
|
113 | npm install --save-dev @testing-library/react-hooks
|
114 | ```
|
115 |
|
116 | ### Peer Dependencies
|
117 |
|
118 | `react-hooks-testing-library` does not come bundled with a version of
|
119 | [`react`](https://www.npmjs.com/package/react) or
|
120 | [`react-test-renderer`](https://www.npmjs.com/package/react-test-renderer) to allow you to install
|
121 | the specific version you want to test against. Generally, the installed versions for `react` and
|
122 | `react-test-renderer` should have matching versions:
|
123 |
|
124 | ```sh
|
125 | npm install react@^16.9.0
|
126 | npm install --save-dev react-test-renderer@^16.9.0
|
127 | ```
|
128 |
|
129 | > **NOTE: The minimum supported version of `react` and `react-test-renderer` is `^16.9.0`.**
|
130 |
|
131 | ## API
|
132 |
|
133 | See the [API reference](https://react-hooks-testing-library.com/reference/api).
|
134 |
|
135 | ## Contributors
|
136 |
|
137 | Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
|
138 |
|
139 |
|
140 |
|
141 |
|
142 | <table>
|
143 | <tr>
|
144 | <td align="center"><a href="https://github.com/mpeyper"><img src="https://avatars0.githubusercontent.com/u/23029903?v=4" width="100px;" alt=""/><br /><sub><b>Michael Peyper</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=mpeyper" title="Code">💻</a> <a href="#design-mpeyper" title="Design">🎨</a> <a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=mpeyper" title="Documentation">📖</a> <a href="#ideas-mpeyper" title="Ideas, Planning, & Feedback">🤔</a> <a href="#infra-mpeyper" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#platform-mpeyper" title="Packaging/porting to new platform">📦</a> <a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=mpeyper" title="Tests">⚠️</a> <a href="#tool-mpeyper" title="Tools">🔧</a></td>
|
145 | <td align="center"><a href="https://github.com/otofu-square"><img src="https://avatars0.githubusercontent.com/u/10118235?v=4" width="100px;" alt=""/><br /><sub><b>otofu-square</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=otofu-square" title="Code">💻</a></td>
|
146 | <td align="center"><a href="https://github.com/ab18556"><img src="https://avatars2.githubusercontent.com/u/988696?v=4" width="100px;" alt=""/><br /><sub><b>Patrick P. Henley</b></sub></a><br /><a href="#ideas-ab18556" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/testing-library/react-hooks-testing-library/pulls?q=is%3Apr+reviewed-by%3Aab18556" title="Reviewed Pull Requests">👀</a></td>
|
147 | <td align="center"><a href="https://twitter.com/matiosfm"><img src="https://avatars3.githubusercontent.com/u/7120471?v=4" width="100px;" alt=""/><br /><sub><b>Matheus Marques</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=marquesm91" title="Code">💻</a></td>
|
148 | <td align="center"><a href="https://ca.linkedin.com/in/dhruvmpatel"><img src="https://avatars1.githubusercontent.com/u/19353311?v=4" width="100px;" alt=""/><br /><sub><b>Dhruv Patel</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/issues?q=author%3Adhruv-m-patel" title="Bug reports">🐛</a> <a href="https://github.com/testing-library/react-hooks-testing-library/pulls?q=is%3Apr+reviewed-by%3Adhruv-m-patel" title="Reviewed Pull Requests">👀</a></td>
|
149 | <td align="center"><a href="https://ntucker.true.io"><img src="https://avatars0.githubusercontent.com/u/866147?v=4" width="100px;" alt=""/><br /><sub><b>Nathaniel Tucker</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/issues?q=author%3Antucker" title="Bug reports">🐛</a> <a href="https://github.com/testing-library/react-hooks-testing-library/pulls?q=is%3Apr+reviewed-by%3Antucker" title="Reviewed Pull Requests">👀</a></td>
|
150 | <td align="center"><a href="https://github.com/sgrishchenko"><img src="https://avatars3.githubusercontent.com/u/15995890?v=4" width="100px;" alt=""/><br /><sub><b>Sergei Grishchenko</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=sgrishchenko" title="Code">💻</a> <a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=sgrishchenko" title="Documentation">📖</a> <a href="#ideas-sgrishchenko" title="Ideas, Planning, & Feedback">🤔</a></td>
|
151 | </tr>
|
152 | <tr>
|
153 | <td align="center"><a href="https://github.com/josepot"><img src="https://avatars1.githubusercontent.com/u/8620144?v=4" width="100px;" alt=""/><br /><sub><b>Josep M Sobrepere</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=josepot" title="Documentation">📖</a></td>
|
154 | <td align="center"><a href="https://github.com/mtinner"><img src="https://avatars0.githubusercontent.com/u/5487448?v=4" width="100px;" alt=""/><br /><sub><b>Marcel Tinner</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=mtinner" title="Documentation">📖</a></td>
|
155 | <td align="center"><a href="https://github.com/FredyC"><img src="https://avatars0.githubusercontent.com/u/1096340?v=4" width="100px;" alt=""/><br /><sub><b>Daniel K.</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/issues?q=author%3AFredyC" title="Bug reports">🐛</a> <a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=FredyC" title="Code">💻</a></td>
|
156 | <td align="center"><a href="https://github.com/VinceMalone"><img src="https://avatars0.githubusercontent.com/u/2516349?v=4" width="100px;" alt=""/><br /><sub><b>Vince Malone</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=VinceMalone" title="Code">💻</a></td>
|
157 | <td align="center"><a href="https://github.com/doppelmutzi"><img src="https://avatars1.githubusercontent.com/u/4130968?v=4" width="100px;" alt=""/><br /><sub><b>Sebastian Weber</b></sub></a><br /><a href="#blog-doppelmutzi" title="Blogposts">📝</a></td>
|
158 | <td align="center"><a href="https://gillchristian.xyz"><img src="https://avatars2.githubusercontent.com/u/8309423?v=4" width="100px;" alt=""/><br /><sub><b>Christian Gill</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=gillchristian" title="Documentation">📖</a></td>
|
159 | <td align="center"><a href="https://jsjoe.io"><img src="https://avatars3.githubusercontent.com/u/3806031?v=4" width="100px;" alt=""/><br /><sub><b>JavaScript Joe</b></sub></a><br /><a href="#tutorial-jsjoeio" title="Tutorials">✅</a></td>
|
160 | </tr>
|
161 | <tr>
|
162 | <td align="center"><a href="http://frontstuff.io"><img src="https://avatars1.githubusercontent.com/u/5370675?v=4" width="100px;" alt=""/><br /><sub><b>Sarah Dayan</b></sub></a><br /><a href="#platform-sarahdayan" title="Packaging/porting to new platform">📦</a></td>
|
163 | <td align="center"><a href="https://github.com/102"><img src="https://avatars1.githubusercontent.com/u/5839225?v=4" width="100px;" alt=""/><br /><sub><b>Roman Gusev</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=102" title="Documentation">📖</a></td>
|
164 | <td align="center"><a href="https://github.com/hemlok"><img src="https://avatars2.githubusercontent.com/u/9043345?v=4" width="100px;" alt=""/><br /><sub><b>Adam Seckel</b></sub></a><br /><a href="https://github.com/testing-library/react-hooks-testing-library/commits?author=hemlok" title="Code">💻</a></td>
|
165 | </tr>
|
166 | </table>
|
167 |
|
168 |
|
169 |
|
170 |
|
171 |
|
172 |
|
173 | This project follows the [all-contributors](https://allcontributors.org/) specification.
|
174 | Contributions of any kind welcome!
|
175 |
|
176 | ## Issues
|
177 |
|
178 | _Looking to contribute? Look for the
|
179 | [Good First Issue](https://github.com/testing-library/react-hooks-testing-library/issues?utf8=✓&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A"good+first+issue"+)
|
180 | label._
|
181 |
|
182 | ### 🐛 Bugs
|
183 |
|
184 | Please file an issue for bugs, missing documentation, or unexpected behavior.
|
185 |
|
186 | [**See Bugs**](https://github.com/testing-library/react-hooks-testing-library/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc)
|
187 |
|
188 | ### 💡 Feature Requests
|
189 |
|
190 | Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps
|
191 | maintainers prioritize what to work on.
|
192 |
|
193 | [**See Feature Requests**](https://github.com/testing-library/react-hooks-testing-library/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen)
|
194 |
|
195 | ### ❓ Questions
|
196 |
|
197 | For questions related to using the library, you can
|
198 | [raise issue here](https://github.com/testing-library/react-hooks-testing-library/issues/new), or
|
199 | visit a support community:
|
200 |
|
201 | - [Reactiflux on Discord](https://www.reactiflux.com/)
|
202 | - [Stack Overflow](https://stackoverflow.com/questions/tagged/react-hooks-testing-library)
|
203 |
|
204 | ## LICENSE
|
205 |
|
206 | MIT
|