React Testing Library does not require any configuration to be used. However,
there are some things you can do when configuring your testing framework to
reduce some boilerplate. In these docs we'll demonstrate configuring Jest, but
you should be able to do similar things with
any testing framework (React Testing Library does not
require that you use Jest).
Adding options to your global test config can simplify the setup and teardown of tests in individual files.
It's often useful to define a custom render method that includes things like
global context providers, data stores, etc. To make this available globally, one
approach is to define a utility file that re-exports everything from
React Testing Library. You can replace React Testing Library with this file in
all your imports. See below for a way to
make your test util file accessible without using relative paths.
The example below sets up data providers using the
Babel versions lower than 7 throw an error when trying to override the named export in the example above. See #169 and the workaround below.
You can use CommonJS modules instead of ES modules, which should work in Node:
Add custom queries
Generally you should not need to create custom queries for react-testing-library. Where you do use it, you should consider whether your new queries encourage you to test in a user-centric way, without testing implementation details.
You can define your own custom queries as described in the
Custom Queries documentation, or
helper. Then you can use them in any render call using the
queries option. To
make the custom queries available globally, you can add them to your custom
render method as shown below.
In the example below, a new set of query variants are created for getting
data-cy, a "test ID" convention mentioned in the
You can then override and append the new queries via the render function by
If you want to add custom queries globally, you can do this by defining a custom render method:
You can then use your custom queries as you would any other query:
Configuring Jest with Test Utils
To make your custom test file accessible in your Jest test files without using
relative imports (
../../test-utils), add the folder containing the file to the
This will make all the
.js files in the test-utils directory importable
This can't be used with Create React App.
If you're using TypeScript, merge this into your
tsconfig.json. If you're
using Create React App without TypeScript, save this to
Jest 24 (or lower) and defaults
If you're using the Jest testing framework version 24 or lower with the default
configuration, it's recommended to use
as Jest uses a version of the jsdom environment that misses some features and
fixes, required by React Testing Library.
jest-environment-jsdom-fifteen as the
Using without Jest
If you're running your tests in the browser bundled with webpack (or similar)
React Testing Library should work out of the box for you. However, most
people using React Testing Library are using it with the Jest testing framework
testEnvironment set to
jest-environment-jsdom (which is the default
configuration with Jest).
runs in Node. If you're not using Jest and you would like to run your tests in
Node, then you must install jsdom yourself. There's also a package called
global-jsdom which can be used to setup the global environment to simulate the
With mocha, the test command would look something like this:
Skipping Auto Cleanup
Cleanup is called after each test automatically by default
if the testing framework you're using supports the
afterEach global (like
mocha, Jest, and Jasmine). However, you may choose to skip the auto cleanup by
RTL_SKIP_AUTO_CLEANUP env variable to 'true'. You can do this with
cross-env like so:
To make this even easier, you can also simply import
@testing-library/react/dont-cleanup-after-each which will do the same thing.
Just make sure you do this before importing
@testing-library/react. You could
do this with Jest's
Or with mocha's
Alternatively, you could import
@testing-library/react/pure in all your tests
that you don't want the
cleanup to run and the
afterEach won't be setup
Auto Cleanup in Mocha's watch mode
When using Mocha in watch mode, the globally registered cleanup is run only the first time after each test. Therefore, subsequent runs will most likely fail with a TestingLibraryElementError: Found multiple elements error.
To enable automatic cleanup in Mocha's watch mode, add a cleanup
root hook. Create a
mocha-watch-cleanup-after-each.js file with the following contents:
And register it using mocha's