Testing React components with Jest and Enzyme

August 2019: This article is out of date, check my new article about testing React components with Jest and Enzyme.

October 2017: the article was updated to React 16 and Enzyme 3.

Some people say that testing React components is useless and in many cases it is, but there are a few cases when I think it’s useful:

component libraries,
open source projects,
integration with third-party components,
bugs, to prevent regressions.

I’ve tried many tools and finally have found a combination that I like enough to suggest to other developers:

Jest, a test runner;
Enzyme, a testing utility for React;
enzyme-to-json to convert Enzyme wrappers for Jest snapshot matcher.

For the most of my tests I use shallow rendering with Jest snapshots.

Shallow rendering

Shallow rendering renders only component itself without its children. So if you change something in a child component it won’t change shallow output of your component. Or a bug, introduced to a child component, won’t break your component’s test. It also doesn’t require DOM.

For example this component:

const ButtonWithIcon = ({ icon, children }) => (
  <button>
    <Icon icon={icon} />
    {children}
  </button>
);

Will be rendered by React like this:

<button>
  <i class="icon icon_coffee"></i>
  Hello Jest!
</button>

But like this with shallow rendering:

<button>
  <Icon icon="coffee" />
  Hello Jest!
</button>

Note that the Icon component was not rendered.

Snapshot testing

Jest snapshots are like those old text UIs with windows and buttons made of text characters: it’s a rendered output of your component stored in a text file.

You tell Jest that you want to be sure that output of this component should never change accidentally and Jest saves it to a file that looks like this:

exports[`test should render a label 1`] = `
<label
  className="isBlock">
  Hello Jest!
</label>
`;
 
exports[`test should render a small label 1`] = `
<label
  className="isBlock isSmall">
  Hello Jest!
</label>
`;

Every time you change your markup Jest will show you a diff and ask you to update a snapshot if the change was intended.

Jest stores snapshots besides your tests in files like __snapshots__/Label.spec.js.snap and you need to commit them with your code.

Why Jest

Very fast.
Snapshot testing.
Awesome interactive watch mode that reruns only tests that are relevant to your changes.
Helpful fail messages.
Simple configuration.
Mocks and spies.
Coverage report with a single command-line switch.
Active development.
Impossible to write silently wrong asserts like expect(foo).to.be.a.function instead of expect(foo).to.be.a('function') in Chai because it’s the only natural thing to write after (correct) expect(foo).to.be.true.

Why Enzyme

Convenient utilities to work with shallow rendering, static rendered markup or DOM rendering.
jQuery-like API to find elements, read props, and so on

Setting up

First install all the dependencies including peer dependencies:

npm install --save-dev jest react-test-renderer enzyme enzyme-adapter-react-16 enzyme-to-json

You’ll also need babel-jest for Babel and ts-jest for TypeScript.

Update your package.json:

"scripts": {
  "test": "jest",
  "test:watch": "jest --watch",
  "test:coverage": "jest --coverage"
},
"jest": {
  "setupFiles": ["./test/jestsetup.js"],
  "snapshotSerializers": ["enzyme-to-json/serializer"]
}

snapshotSerializers allows you to pass Enzyme wrappers directly to Jest’s snapshot matcher, without converting them manually by calling enzyme-to-json’s toJson function.

Create a test/jestsetup.js file to customize Jest environment (see setupFiles above):

import Enzyme, { shallow, render, mount } from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';
 
// React 16 Enzyme adapter
Enzyme.configure({ adapter: new Adapter() });
 
// Make Enzyme functions available in all test files without importing
global.shallow = shallow;
global.render = render;
global.mount = mount;

For CSS Modules also add to jest section in your package.json:

"jest": {
  "moduleNameMapper": {
    "^.+\\.(css|scss)$": "identity-obj-proxy"
  }
}

And run npm install --save-dev identity-obj-proxy.

Note that identity-obj-proxy requires node --harmony-proxies flag for Node 4 and 5.

Writing tests

Testing basic component rendering

That’s enough for most non-interactive components:

test('render a label', () => {
  const wrapper = shallow(<Label>Hello Jest!</Label>);
  expect(wrapper).toMatchSnapshot();
});
 
test('render a small label', () => {
  const wrapper = shallow(<Label small>Hello Jest!</Label>);
  expect(wrapper).toMatchSnapshot();
});
 
test('render a grayish label', () => {
  const wrapper = shallow(<Label light>Hello Jest!</Label>);
  expect(wrapper).toMatchSnapshot();
});

Testing props

Sometimes you want to be more explicit and see real values in tests. In that case use Enzyme API with regular Jest assertions:

test('render a document title', () => {
  const wrapper = shallow(<DocumentTitle title="Events" />);
  expect(wrapper.prop('title')).toEqual('Events');
});
 
test('render a document title and a parent title', () => {
  const wrapper = shallow(
    <DocumentTitle title="Events" parent="Event Radar" />
  );
  expect(wrapper.prop('title')).toEqual('Events — Event Radar');
});

In some cases you just can’t use snapshots. For example if you have random IDs or something like that:

test('render a popover with a random ID', () => {
  const wrapper = shallow(<Popover>Hello Jest!</Popover>);
  expect(wrapper.prop('id')).toMatch(/Popover\d+/);
});

Testing events

You can simulate an event like click or change and then compare component to a snapshot:

test('render Markdown in preview mode', () => {
  const wrapper = shallow(<MarkdownEditor value="*Hello* Jest!" />);
 
  expect(wrapper).toMatchSnapshot();
 
  wrapper.find('[name="toggle-preview"]').simulate('click');
 
  expect(wrapper).toMatchSnapshot();
});

Sometimes you want to interact with an element in a child component to test effect in your component. For that you need a proper DOM rendering with Enzyme’s mount method:

test('open a code editor', () => {
  const wrapper = mount(<Playground code={code} />);
 
  expect(wrapper.find('.ReactCodeMirror')).toHaveLength(0);
 
  wrapper.find('button').simulate('click');
 
  expect(wrapper.find('.ReactCodeMirror')).toHaveLength(1);
});

Testing event handlers

Similar to events testing but instead of testing component’s rendered output with a snapshot use Jest’s mock function to test an event handler itself:

test('pass a selected value to the onChange handler', () => {
  const value = '2';
  const onChange = jest.fn();
  const wrapper = shallow(
    <Select items={ITEMS} onChange={onChange} />
  );
 
  expect(wrapper).toMatchSnapshot();
 
  wrapper.find('select').simulate('change', {
    target: { value }
  });
 
  expect(onChange).toBeCalledWith(value);
});

Not only JSX

Jest snapshots work with JSON so you can test any function that returns JSON the same way you test your components:

test('accept custom properties', () => {
  const wrapper = shallow(
    <Layout
      flexBasis={0}
      flexGrow={1}
      flexShrink={1}
      flexWrap="wrap"
      justifyContent="flex-end"
      alignContent="center"
      alignItems="center"
    />
  );
  expect(wrapper.prop('style')).toMatchSnapshot();
});

Debugging and troubleshooting

Debugging shallow renderer output

Use Enzyme’s debug method to print shallow renderer’s output:

const wrapper = shallow(/*~*/);
console.log(wrapper.debug());

Failing tests with enabled coverage

When your tests fail with --coverage flag with diff like this:

-<Button
+<Component

Try to replace arrow function component with regular function:

- export default const Button = ({ children }) => {
+ export default function Button({ children }) {

requestAnimationFrame error

You may see an error like this when you run your tests:

console.error node_modules/fbjs/lib/warning.js:42
  Warning: React depends on requestAnimationFrame. Make sure that you load a polyfill in older browsers. http://fb.me/react-polyfills

React 16 depends on requestAnimationFrame, so you need to add a polyfill to your tests:

// test/jestsetup.js
import 'raf/polyfill';

Resources

Jest cheat sheet
Testing React Applications by Max Stoiber
Migrating to Jest by Kent C. Dodds
Migrating AVA to Jest by Jason Brown

Thanks to Chris Pojer, Max Stoiber and Anna Gerus for proofreading and comments.

Testing React components with Jest and Enzyme

#Shallow rendering

#Snapshot testing

#Why Jest

#Why Enzyme

#Setting up

#Writing tests

#Testing basic component rendering

#Testing props

#Testing events

#Testing event handlers

#Not only JSX

#Debugging and troubleshooting

#Debugging shallow renderer output

#Failing tests with enabled coverage

#requestAnimationFrame error

#Resources