Running Tests

Note: this feature is available with react-scripts@0.3.0 and higher.

Read the migration guide to learn how to enable it in older projects!

Create React App uses Jest as its test runner. To prepare for this integration, we did a major revamp of Jest so if you heard bad things about it years ago, give it another try.

Jest is a Node-based runner. This means that the tests always run in a Node environment and not in a real browser. This lets us enable fast iteration speed and prevent flakiness.

While Jest provides browser globals such as window thanks to jsdom, they are only approximations of the real browser behavior. Jest is intended to be used for unit tests of your logic and your components rather than the DOM quirks.

We recommend that you use a separate tool for browser end-to-end tests if you need them. They are beyond the scope of Create React App.

Filename Conventions

Jest will look for test files with any of the following popular naming conventions:

  • Files with .js suffix in tests folders.
  • Files with .test.js suffix.
  • Files with .spec.js suffix.The .test.js / .spec.js files (or the tests folders) can be located at any depth under the src top level folder.

We recommend to put the test files (or tests folders) next to the code they are testing so that relative imports appear shorter. For example, if App.test.js and App.js are in the same folder, the test just needs to import App from './App' instead of a long relative path. Collocation also helps find tests more quickly in larger projects.

Command Line Interface

When you run npm test, Jest will launch in watch mode*. Every time you save a file, it will re-run the tests, just like npm start recompiles the code.

The watcher includes an interactive command-line interface with the ability to run all tests, or focus on a search pattern. It is designed this way so that you can keep it open and enjoy fast re-runs. You can learn the commands from the “Watch Usage” note that the watcher prints after every run:

Jest watch mode

*Although we recommend running your tests in watch mode during development, you can disable this behavior by passing in the —watchAll=false flag. In most CI environments, this is handled for you (see On CI servers).

Version Control Integration

By default, when you run npm test, Jest will only run the tests related to files changed since the last commit. This is an optimization designed to make your tests run fast regardless of how many tests you have. However it assumes that you don’t often commit the code that doesn’t pass the tests.

Jest will always explicitly mention that it only ran tests related to the files changed since the last commit. You can also press a in the watch mode to force Jest to run all tests.

Jest will always run all tests on a continuous integration server or if the project is not inside a Git or Mercurial repository.

Writing Tests

To create tests, add it() (or test()) blocks with the name of the test and its code. You may optionally wrap them in describe() blocks for logical grouping but this is neither required nor recommended.

Jest provides a built-in expect() global function for making assertions. A basic test could look like this:

  1. import sum from './sum';
  3. it('sums numbers', () => {
  4.   expect(sum(1, 2)).toEqual(3);
  5.   expect(sum(2, 2)).toEqual(4);
  6. });

All expect() matchers supported by Jest are extensively documented here.You can also use jest.fn() and expect(fn).toBeCalled() to create “spies” or mock functions.

Testing Components

There is a broad spectrum of component testing techniques. They range from a “smoke test” verifying that a component renders without throwing, to shallow rendering and testing some of the output, to full rendering and testing component lifecycle and state changes.

Different projects choose different testing tradeoffs based on how often components change, and how much logic they contain. If you haven’t decided on a testing strategy yet, we recommend that you start with creating simple smoke tests for your components:

  1. import React from 'react';
  2. import ReactDOM from 'react-dom';
  3. import App from './App';
  5. it('renders without crashing', () => {
  6.   const div = document.createElement('div');
  7.   ReactDOM.render(<App />, div);
  8. });

This test mounts a component and makes sure that it didn’t throw during rendering. Tests like this provide a lot of value with very little effort so they are great as a starting point, and this is the test you will find in src/App.test.js.

When you encounter bugs caused by changing components, you will gain a deeper insight into which parts of them are worth testing in your application. This might be a good time to introduce more specific tests asserting specific expected output or behavior.

Option 1: Shallow Rendering

If you’d like to test components in isolation from the child components they render, we recommend using shallow() rendering API from Enzyme. To install it, run:

  1. npm install --save enzyme enzyme-adapter-react-16 react-test-renderer

Alternatively you may use yarn:

  1. yarn add enzyme enzyme-adapter-react-16 react-test-renderer

As of Enzyme 3, you will need to install Enzyme along with an Adapter corresponding to the version of React you are using. (The examples above use the adapter for React 16.)

The adapter will also need to be configured in your global setup file:

src/setupTests.js

  1. import { configure } from 'enzyme';
  2. import Adapter from 'enzyme-adapter-react-16';
  4. configure({ adapter: new Adapter() });

Note: Keep in mind that if you decide to "eject" before creating src/setupTests.js, the resulting package.json file won't contain any reference to it. Read here to learn how to add this after ejecting.

Now you can write a smoke test with it:

  1. import React from 'react';
  2. import { shallow } from 'enzyme';
  3. import App from './App';
  5. it('renders without crashing', () => {
  6.   shallow(<App />);
  7. });

Unlike the previous smoke test using ReactDOM.render(), this test only renders <App> and doesn’t go deeper. For example, even if <App> itself renders a <Button> that throws, this test will pass. Shallow rendering is great for isolated unit tests, but you may still want to create some full rendering tests to ensure the components integrate correctly. Enzyme supports full rendering with mount(), and you can also use it for testing state changes and component lifecycle.

You can read the Enzyme documentation for more testing techniques. Enzyme documentation uses Chai and Sinon for assertions but you don’t have to use them because Jest provides built-in expect() and jest.fn() for spies.

Here is an example from Enzyme documentation that asserts specific output, rewritten to use Jest matchers:

  1. import React from 'react';
  2. import { shallow } from 'enzyme';
  3. import App from './App';
  5. it('renders welcome message', () => {
  6.   const wrapper = shallow(<App />);
  7.   const welcome = <h2>Welcome to React</h2>;
  8.   // expect(wrapper.contains(welcome)).toBe(true);
  9.   expect(wrapper.contains(welcome)).toEqual(true);
  10. });

All Jest matchers are extensively documented here.Nevertheless you can use a third-party assertion library like Chai if you want to, as described below.

Additionally, you might find jest-enzyme helpful to simplify your tests with readable matchers. The above contains code can be written more simply with jest-enzyme.

  1. expect(wrapper).toContainReact(welcome);

To enable this, install jest-enzyme:

  1. npm install --save jest-enzyme

Alternatively you may use yarn:

  1. yarn add jest-enzyme

Import it in src/setupTests.js to make its matchers available in every test:

  1. import 'jest-enzyme';

Option 2: React Testing Library

As an alternative or companion to enzyme, you may consider using react-testing-library. react-testing-library is a library for testing React components in a way that resembles the way the components are used by end users. It is well suited for unit, integration, and end-to-end testing of React components and applications. It works more directly with DOM nodes, and therefore it's recommended to use with jest-dom for improved assertions.

To install react-testing-library and jest-dom, you can run:

  1. npm install --save @testing-library/react @testing-library/jest-dom

Alternatively you may use yarn:

  1. yarn add @testing-library/react @testing-library/jest-dom

Similar to enzyme you can create a src/setupTests.js file to avoid boilerplate in your test files:

  1. // react-testing-library renders your components to document.body,
  2. // this will ensure they're removed after each test.
  3. import '@testing-library/react/cleanup-after-each';
  4. // this adds jest-dom's custom assertions
  5. import '@testing-library/jest-dom/extend-expect';

Here's an example of using react-testing-library and jest-dom for testing that the <App /> component renders "Welcome to React".

  1. import React from 'react';
  2. import { render } from '@testing-library/react';
  3. import App from './App';
  5. it('renders welcome message', () => {
  6.   const { getByText } = render(<App />);
  7.   expect(getByText('Welcome to React')).toBeInTheDocument();
  8. });

Learn more about the utilities provided by react-testing-library to facilitate testing asynchronous interactions as well as selecting form elements from the react-testing-library documentation and examples.

Using Third Party Assertion Libraries

We recommend that you use expect() for assertions and jest.fn() for spies. If you are having issues with them please file those against Jest, and we’ll fix them. We intend to keep making them better for React, supporting, for example, pretty-printing React elements as JSX.

However, if you are used to other libraries, such as Chai and Sinon, or if you have existing code using them that you’d like to port over, you can import them normally like this:

  1. import sinon from 'sinon';
  2. import { expect } from 'chai';

and then use them in your tests like you normally do.

Initializing Test Environment

Note: this feature is available with react-scripts@0.4.0 and higher.

If your app uses a browser API that you need to mock in your tests or if you just need a global setup before running your tests, add a src/setupTests.js to your project. It will be automatically executed before running your tests.

For example:

src/setupTests.js

  1. const localStorageMock = {
  2.   getItem: jest.fn(),
  3.   setItem: jest.fn(),
  4.   removeItem: jest.fn(),
  5.   clear: jest.fn(),
  6. };
  7. global.localStorage = localStorageMock;

Note: Keep in mind that if you decide to "eject" before creating src/setupTests.js, the resulting package.json file won't contain any reference to it, so you should manually create the property setupTestFrameworkScriptFile in the configuration for Jest, something like the following:

  1. "jest": {  // …  "setupTestFrameworkScriptFile": "<rootDir>/src/setupTests.js" }

Focusing and Excluding Tests

You can replace it() with xit() to temporarily exclude a test from being executed.Similarly, fit() lets you focus on a specific test without running any other tests.

Coverage Reporting

Jest has an integrated coverage reporter that works well with ES6 and requires no configuration.Run npm test — —coverage (note extra — in the middle) to include a coverage report like this:

coverage report

Note that tests run much slower with coverage so it is recommended to run it separately from your normal workflow.

Configuration

The default Jest coverage configuration can be overridden by adding any of the following supported keys to a Jest config in your package.json.

Supported overrides:

  1. {
  2.   "name": "your-package",
  3.   "jest": {
  4.     "collectCoverageFrom": [
  5.       "src/**/*.{js,jsx,ts,tsx}",
  6.       "!<rootDir>/node_modules/",
  7.       "!<rootDir>/path/to/dir/"
  8.     ],
  9.     "coverageThreshold": {
  10.       "global": {
  11.         "branches": 90,
  12.         "functions": 90,
  13.         "lines": 90,
  14.         "statements": 90
  15.       }
  16.     },
  17.     "coverageReporters": ["text"],
  18.     "snapshotSerializers": ["my-serializer-module"]
  19.   }
  20. }

Continuous Integration

By default npm test runs the watcher with interactive CLI. However, you can force it to run tests once and finish the process by setting an environment variable called CI.

When creating a build of your application with npm run build linter warnings are not checked by default. Like npm test, you can force the build to perform a linter warning check by setting the environment variable CI. If any warnings are encountered then the build fails.

Popular CI servers already set the environment variable CI by default but you can do this yourself too:

On CI servers

Travis CI

  • Following the Travis Getting started guide for syncing your GitHub repository with Travis. You may need to initialize some settings manually in your profile page.
  • Add a .travis.yml file to your git repository.
  1. language: node_js
  2. node_js:
  3.   - 8
  4. cache:
  5.   directories:
  6.     - node_modules
  7. script:
  8.   - npm run build
  9.   - npm test

CircleCI

Follow this article to set up CircleCI with a Create React App project.

On your own environment

Windows (cmd.exe)

  1. set CI=true&&npm test
  1. set CI=true&&npm run build

(Note: the lack of whitespace is intentional.)

Windows (Powershell)

  1. ($env:CI = "true") -and (npm test)
  1. ($env:CI = "true") -and (npm run build)

Linux, macOS (Bash)

  1. CI=true npm test
  1. CI=true npm run build

The test command will force Jest to run in CI-mode, and tests will only run once instead of launching the watcher.

For non-CI environments, you can simply pass the —watchAll=false flag to disable test-watching.

The build command will check for linter warnings and fail if any are found.

Disabling jsdom

If you know that none of your tests depend on jsdom, you can safely set —env=node, and your tests will run faster:

  1.   "scripts": {
  2.     "start": "react-scripts start",
  3.     "build": "react-scripts build",
  4. -   "test": "react-scripts test"
  5. +   "test": "react-scripts test --env=node"

To help you make up your mind, here is a list of APIs that need jsdom:

Snapshot Testing

Snapshot testing is a feature of Jest that automatically generates text snapshots of your components and saves them on the disk so if the UI output changes, you get notified without manually writing any assertions on the component output. Read more about snapshot testing.

Editor Integration

If you use Visual Studio Code, there is a Jest extension which works with Create React App out of the box. This provides a lot of IDE-like features while using a text editor: showing the status of a test run with potential fail messages inline, starting and stopping the watcher automatically, and offering one-click snapshot updates.

VS Code Jest Preview