Test Utilities

Importing

import ReactTestUtils from 'react-dom/test-utils'; // ES6
var ReactTestUtils = require('react-dom/test-utils'); // ES5 with npm

Overview

ReactTestUtils makes it easy to test React components in the testing framework of your choice. At Facebook we use Jest for painless JavaScript testing. Learn how to get started with Jest through the Jest website’s React Tutorial.

Note:

Airbnb has released a testing utility called Enzyme, which makes it easy to assert, manipulate, and traverse your React Components’ output. If you’re deciding on a unit testing utility to use together with Jest, or any other test runner, it’s worth checking out: http://airbnb.io/enzyme/

Alternatively, there is another testing utility called react-testing-library designed to enable and encourage writing tests that use your components as the end users use them. It also works with any test runner: https://git.io/react-testing-library

• Simulate
• renderIntoDocument()
• mockComponent()
• isElement()
• isElementOfType()
• isDOMComponent()
• isCompositeComponent()
• isCompositeComponentWithType()
• findAllInRenderedTree()
• scryRenderedDOMComponentsWithClass()
• findRenderedDOMComponentWithClass()
• scryRenderedDOMComponentsWithTag()
• findRenderedDOMComponentWithTag()
• scryRenderedComponentsWithType()
• findRenderedComponentWithType()

Reference

Shallow Rendering

When writing unit tests for React, shallow rendering can be helpful. Shallow rendering lets you render a component “one level deep” and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM.

Note:

The shallow renderer has moved to react-test-renderer/shallow.
Learn more about shallow rendering on its reference page.

Other Utilities

Simulate

Simulate.{eventName}(
  element,
  [eventData]
)

Simulate an event dispatch on a DOM node with optional eventData event data.

Simulate has a method for every event that React understands.

Clicking an element

// <button ref={(node) => this.button = node}>...</button>
const node = this.button;
ReactTestUtils.Simulate.click(node);

Changing the value of an input field and then pressing ENTER.

// <input ref={(node) => this.textInput = node} />
const node = this.textInput;
node.value = 'giraffe';
ReactTestUtils.Simulate.change(node);
ReactTestUtils.Simulate.keyDown(node, {key: "Enter", keyCode: 13, which: 13});

Note

You will have to provide any event property that you’re using in your component (e.g. keyCode, which, etc…) as React is not creating any of these for you.

renderIntoDocument()

renderIntoDocument(element)

Render a React element into a detached DOM node in the document. This function requires a DOM.

Note:

You will need to have window, window.document and window.document.createElement globally available before you import React. Otherwise React will think it can’t access the DOM and methods like setState won’t work.

mockComponent()

mockComponent(
  componentClass,
  [mockTagName]
)

Pass a mocked component module to this method to augment it with useful methods that allow it to be used as a dummy React component. Instead of rendering as usual, the component will become a simple <div> (or other tag if mockTagName is provided) containing any provided children.

Note:

mockComponent() is a legacy API. We recommend using shallow rendering or jest.mock() instead.

isElement()

isElement(element)

Returns true if element is any React element.

isElementOfType()

isElementOfType(
  element,
  componentClass
)

Returns true if element is a React element whose type is of a React componentClass.

isDOMComponent()

isDOMComponent(instance)

Returns true if instance is a DOM component (such as a <div> or <span>).

isCompositeComponent()

isCompositeComponent(instance)

Returns true if instance is a user-defined component, such as a class or a function.

isCompositeComponentWithType()

isCompositeComponentWithType(
  instance,
  componentClass
)

Returns true if instance is a component whose type is of a React componentClass.

findAllInRenderedTree()

findAllInRenderedTree(
  tree,
  test
)

Traverse all components in tree and accumulate all components where test(component) is true. This is not that useful on its own, but it’s used as a primitive for other test utils.

scryRenderedDOMComponentsWithClass()

scryRenderedDOMComponentsWithClass(
  tree,
  className
)

Finds all DOM elements of components in the rendered tree that are DOM components with the class name matching className.

findRenderedDOMComponentWithClass()

findRenderedDOMComponentWithClass(
  tree,
  className
)

Like scryRenderedDOMComponentsWithClass() but expects there to be one result, and returns that one result, or throws exception if there is any other number of matches besides one.

scryRenderedDOMComponentsWithTag()

scryRenderedDOMComponentsWithTag(
  tree,
  tagName
)

Finds all DOM elements of components in the rendered tree that are DOM components with the tag name matching tagName.

findRenderedDOMComponentWithTag()

findRenderedDOMComponentWithTag(
  tree,
  tagName
)

Like scryRenderedDOMComponentsWithTag() but expects there to be one result, and returns that one result, or throws exception if there is any other number of matches besides one.

scryRenderedComponentsWithType()

scryRenderedComponentsWithType(
  tree,
  componentClass
)

Finds all instances of components with type equal to componentClass.

findRenderedComponentWithType()

findRenderedComponentWithType(
  tree,
  componentClass
)

Same as scryRenderedComponentsWithType() but expects there to be one result and returns that one result, or throws exception if there is any other number of matches besides one.