Simple and complete React hooks testing utilities that encourage good testing practices.
Read The Docs
Since we updated our build process to use esbuild, we no longer need this repo. We are now using
the regular version of @testing-library/react-hooks. I'll keep this version around just to make
sure things work, but it can now be safely deleted.
The built version of this library that is downloaded when you run
npm install @testing-library/react-hooks contains a few features that are not supported by
figbuild. This forked version makes the following changes:
- Output code that
figbuildis set up to process. This was accomplished by adding a.browserslistrcfile that lists IE 11 as a supported browser. While we don't actually support IE 11, this does mean the build won't try to use any fancy new language features. - Build with the
--bundleoption. This causes the build script to use Rollup to generate a single script file, instead of separate ES6 modules. This is also required to make the build script care about the.browserslistrcfile. - Update the
mainandtypesfields ofpackage.json. The--bundleoption places the built file in a different ___location, underdistand with a new filename. - Update
tsconfig.jsonto use anES5target. I'm not sure if this does anything, since we're using Babel to build, not Typescript. But whatever, it can't hurt. - Remove "smart" dynamic
requirelogic to choose a renderer.figbuilddoes not support dynamicrequirestatements. I also deleted tests for this logic. - Remove submodules structure. Since we're no longer doing dynamic requires, we also don't need to
output
@testing-library/react-hooks/domand similar directories.
If and when we move off of figbuild, we may be able to un-fork this library.
- The problem
- The solution
- When to use this library
- When not to use this library
- Example
- Installation
- API
- Contributors
- Issues
- LICENSE
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:
Invariant Violation: Hooks can only be called inside the body of a function component.
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.
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.
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.
- You're writing a library with one or more custom hooks that are not directly tied to a component
- You have a complex hook that is difficult to test through component interactions
- Your hook is defined alongside a component and is only used there
- Your hook is easy to test by just testing the components using it
import { useState, useCallback } from 'react'
function useCounter() {
const [count, setCount] = useState(0)
const increment = useCallback(() => setCount((x) => x + 1), [])
return { count, increment }
}
export default useCounterimport { renderHook, act } from '@testing-library/react-hooks'
import useCounter from './useCounter'
test('should increment counter', () => {
const { result } = renderHook(() => useCounter())
act(() => {
result.current.increment()
})
expect(result.current.count).toBe(1)
})More advanced usage can be found in the documentation.
npm install --save-dev @testing-library/react-hooksreact-hooks-testing-library does not come bundled with a version of
react to allow you to install the specific version you want
to test against. It also does not come installed with a specific renderer, we currently support
react-test-renderer and
react-dom. You only need to install one of them,
however, if you do have both installed, we will use react-test-renderer as the default. For more
information see the installation docs.
Generally, the installed versions for react and the selected renderer should have matching
versions:
npm install react@^16.9.0
npm install --save-dev react-test-renderer@^16.9.0NOTE: The minimum supported version of
react,react-test-rendererandreact-domis^16.9.0.
See the API reference.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
Looking to contribute? Look for the Good First Issue label.
Please file an issue for bugs, missing documentation, or unexpected behavior.
Please file an issue to suggest new features. Vote on feature requests by adding a π. This helps maintainers prioritize what to work on.
For questions related to using the library, you can raise issue here, or visit a support community:
MIT