Build Status Code Coverage version downloads MIT License

All Contributors PRs Welcome Code of Conduct Join the community on Spectrum

Watch on GitHub Star on GitHub Tweet

You want to write maintainable tests for your React components. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your testbase to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.

The react-testing-library is a very light-weight solution for testing React components. It provides light utility functions on top of react-dom and react-dom/test-utils, in a way that encourages better testing practices. It's primary guiding principle is:

The more your tests resemble the way your software is used, the more confidence they can give you.

So rather than dealing with instances of rendered react components, your tests will work with actual DOM nodes. The utilities this library provides facilitate querying the DOM in the same way the user would. Finding for elements by their label text (just like a user would), finding links and buttons from their text (like a user would). It also exposes a recommended way to find elements by a data-testid as an "escape hatch" for elements where the text content and label do not make sense or is not practical.

This library encourages your applications to be more accessible and allows you to get your tests closer to using your components the way a user will, which allows your tests to give you more confidence that your application will work when a real user uses it.

This library is a replacement for enzyme. While you can follow these guidelines using enzyme itself, enforcing this is harder because of all the extra utilities that enzyme provides (utilities which facilitate testing implementation details). Read more about this in the FAQ below.

What this library is not:

1. A test runner or framework
2. Specific to a testing framework (though we recommend Jest as our preference, the library works with any framework. See Using Without Jest)

NOTE: This library is built on top of dom-testing-library which is where most of the logic behind the queries is.

• Installation
• Usage
  • render
  • cleanup
• dom-testing-library APIs
  • fireEvent(node: HTMLElement, event: Event)
  • waitForElement
  • wait
  • within
• TextMatch
• query APIs
• queryAll and getAll APIs
• Examples
• Learning Material
• FAQ
• Other Solutions
• Guiding Principles
• Contributors
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
  • ❓ Questions
• LICENSE

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev react-testing-library

This library has a peerDependencies listing for react-dom.

You may also be interested in installing jest-dom so you can use the custom jest matchers

// __tests__/fetch.js
import React from 'react'
import {render, fireEvent, cleanup, waitForElement} from 'react-testing-library'
// this add custom jest matchers from jest-dom
import 'jest-dom/extend-expect'
import axiosMock from 'axios' // the mock lives in a __mocks__ directory
import Fetch from '../fetch' // see the tests for a full implementation
// automatically unmount and cleanup DOM after the test is finished.
afterEach(cleanup)
test('Fetch makes an API call and displays the greeting when load-greeting is clicked', async () => {
 // Arrange
 axiosMock.get.mockResolvedValueOnce({data: {greeting: 'hello there'}})
 const url = '/greeting'
 const {getByText, getByTestId, container} = render(<Fetch url={url} />)
 // Act
 fireEvent.click(getByText('Load Greeting'))
 // let's wait for our mocked `get` request promise to resolve
 // wait will wait until the callback doesn't throw an error
 const greetingTextNode = await waitForElement(() =>
 getByTestId('greeting-text'),
 )
 // Assert
 expect(axiosMock.get).toHaveBeenCalledTimes(1)
 expect(axiosMock.get).toHaveBeenCalledWith(url)
 expect(getByTestId('greeting-text')).toHaveTextContent('hello there')
 expect(getByTestId('ok-button')).toHaveAttribute('disabled')
 // snapshots work great with regular DOM nodes!
 expect(container.firstChild).toMatchSnapshot()
})

Defined as:

function render(
 ui: React.ReactElement<any>,
 options?: {
 /* You wont often use this, expand below for docs on options */
 },
): RenderResult

Render into a container which is appended to document.body. It should be used with cleanup:

import {render, cleanup} from 'react-testing-library'
afterEach(cleanup)
render(<div />)

const table = document.createElement('table')
const {container} = render(<TableBody {...props} />, {
 container: document.body.appendChild(table),
})

In the example above, the render method returns an object that has a few properties:

The containing DOM node of your rendered React Element (rendered using ReactDOM.render). It's a div. This is a regular DOM node, so you can call container.querySelector etc. to inspect the children.

Tip: To get the root element of your rendered element, use container.firstChild.

NOTE: When that root element is a React Fragment, container.firstChild will only get the first child of that Fragment, not the Fragment itself.

The containing DOM node where your React Element is rendered in the container. If you don't specify the baseElement in the options of render, it will default to document.body.

This is useful when the component you want to test renders something outside the container div, e.g. when you want to snapshot test your portal component which renders it's HTML directly in the body.

Note: the queries returned by the render looks into baseElement, so you can use queries to test your portal component without the baseElement.

This method is a shortcut for console.log(prettyDOM(container)).

import {render} from 'react-testing-library'
const HelloWorld = () => <h1>Hello World</h1>
const {debug} = render(<HelloWorld />)
debug()
// <div>
// <h1>Hello World</h1>
// </div>
// you can also pass an element: debug(getByTestId('messages'))

This is a simple wrapper around prettyDOM which is also exposed and comes from dom-testing-library.

It'd probably be better if you test the component that's doing the prop updating to ensure that the props are being updated correctly (see the Guiding Principles section). That said, if you'd prefer to update the props of a rendered component in your test, this function can be used to update props of the rendered component.

import {render} from 'react-testing-library'
const {rerender} = render(<NumberDisplay number={1} />)
// re-render the same component with different props
rerender(<NumberDisplay number={2} />)

Open the tests for a full example of this.

This will cause the rendered component to be unmounted. This is useful for testing what happens when your component is removed from the page (like testing that you don't leave event handlers hanging around causing memory leaks).

This method is a pretty small abstraction over ReactDOM.unmountComponentAtNode

import {render} from 'react-testing-library'
const {container, unmount} = render(<Login />)
unmount()
// your component has been unmounted and now: container.innerHTML === ''

This will search for the label that matches the given TextMatch, then find the element associated with that label.

import {render} from 'react-testing-library'
const {getByLabelText} = render(<Login />)
const inputNode = getByLabelText('Username')
// this would find the input node for the following DOM structures:
// The "for" attribute (NOTE: in JSX with React you'll write "htmlFor" rather than "for")
// <label for="username-input">Username</label>
// <input id="username-input" />
//
// The aria-labelledby attribute
// <label id="username-label">Username</label>
// <input aria-labelledby="username-label" />
//
// Wrapper labels
// <label>Username <input /></label>
//
// It will NOT find the input node for this:
// <label><span>Username</span> <input /></label>
//
// For this case, you can provide a `selector` in the options:
const inputNode = getByLabelText('username', {selector: 'input'})
// and that would work
// Note that <input aria-label="username" /> will also work, but take
// care because this is not a label that users can see on the page. So
// the purpose of your input should be obvious for those users.

Note: This method will throw an error if it cannot find the node. If you don't want this behavior (for example you wish to assert that it doesn't exist), then use queryByLabelText instead.

This will search for all elements with a placeholder attribute and find one that matches the given TextMatch.

import {render} from 'react-testing-library'
const {getByPlaceholderText} = render(<input placeholder="Username" />)
const inputNode = getByPlaceholderText('Username')

NOTE: a placeholder is not a good substitute for a label so you should generally use getByLabelText instead.

This will search for all elements that have a text node with textContent matching the given TextMatch.

import {render} from 'react-testing-library'
const {getByText} = render(<a href="/about">About i️</a>)
const aboutAnchorNode = getByText('about')

This will return the element (normally an <img>) that has the given alt text. Note that it only supports elements which accept an alt attribute: <img>, <input>, and <area> (intentionally excluding <applet> as it's deprecated).

import {render} from 'react-testing-library'
const {getByAltText} = render(
 <img alt="Incredibles 2 Poster" src="/incredibles-2.png" />,
)
const incrediblesPosterImg = getByAltText(/incredibles.*poster$/i)

A shortcut to container.querySelector(`[data-testid="${yourId}"]`) (and it also accepts a TextMatch).

import {render} from 'react-testing-library'
const {getByTestId} = render(<input data-testid="username-input" />)
const usernameInputElement = getByTestId('username-input')

In the spirit of the guiding principles, it is recommended to use this only after getByLabel, getByPlaceholderText or getByText don't work for your use case. Using data-testid attributes do not resemble how your software is used and should be avoided if possible. That said, they are way better than querying based on DOM structure. Learn more about data-testids from the blog post "Making your UI tests resilient to change"

Unmounts React trees that were mounted with render.

import {cleanup, render} from 'react-testing-library'
afterEach(cleanup)
test('renders into document', () => {
 render(<div />)
 // ...
})

Failing to call cleanup when you've called render could result in a memory leak and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests).

If you don't want to add this to every single test file then we recommend that you configure your test framework to run a file before your tests which does this automatically.

For example, to do this with jest, you can use setupTestFrameworkScriptFile:

// jest.config.js
module.exports = {
 setupTestFrameworkScriptFile: require.resolve('./test/setup-test-env.js'),
}

Then:

// test/setup-test-env.js
// add some helpful assertions
import 'jest-dom/extend-expect'
// this is basically: afterEach(cleanup)
import 'react-testing-library/cleanup-after-each'

Or if you're using react-scripts (create-react-app), it has a default value that's set to src/setupTests.js so put the code above in that file.

react-testing-library is built on top of dom-testing-library and re-exports everything from dom-testing-library. Some notable included exports:

Fire DOM events.

React attaches an event handler on the document and handles some DOM events via event delegation (events bubbling up from a target to an ancestor). Because of this, your node must be in the document.body for fireEvent to work with React. This is why render appends your container to document.body. This is an alternative to simulating Synthetic React Events via Simulate. The benefit of using fireEvent over Simulate is that you are testing real DOM events instead of Synthetic Events. This aligns better with the Guiding Principles. (Also Dan Abramov told me to stop use Simulate).

NOTE: If you don't like having to use cleanup (which we have to do because we render into document.body) to get fireEvent working, then feel free to try to chip into making it possible for React to attach event handlers to the rendered node rather than the document. Learn more here: facebook/react#2043

import {render, cleanup, fireEvent} from 'react-testing-library'
// don't forget to clean up the document.body
afterEach(cleanup)
test('clicks submit button', () => {
 const spy = jest.fn()
 const {getByText} = render(<button onClick={spy}>Submit</button>)
 fireEvent(
 getByText('Submit'),
 new MouseEvent('click', {
 bubbles: true, // click events must bubble for React to see it
 cancelable: true,
 }),
 )
 expect(spy).toHaveBeenCalledTimes(1)
})

Convenience methods for firing DOM events. Check out dom-testing-library/src/events.js for a full list as well as default eventProperties.

import {render, fireEvent} from 'react-testing-library'
const {getElementByText} = render(<Form />)
// similar to the above example
// click will bubble for React to see it
const rightClick = {button: 2}
fireEvent.click(getElementByText('Submit'), rightClick)
// default `button` property for click events is set to `0` which is a left click.

If you want to trigger the onChange handler of a controlled component with a different event.target.value, sending value through eventProperties won't work like it does with Simulate. You need to change the element's value property, then use fireEvent to fire a change DOM event.

import {render, fireEvent} from 'react-testing-library'
const {getByLabelText} = render(<Form />)
const comment = getByLabelText('Comment')
comment.value = 'Great advice, I love your posts!'
fireEvent.change(comment)

Read full docs from dom-testing-library

import {render, waitForElement} from 'react-testing-library'
test('waiting for an element', async () => {
 const {getByText} = render(<SearchForm />)
 await waitForElement(() => getByText('Search'))
})

Read full docs from dom-testing-library

It's recommended to prefer waitForElement, but this can be helpful on occasion

import 'jest-dom/extend-expect'
import {render, wait} from 'react-testing-library'
test('can fill in the form after loaded', async () => {
 const {getByLabelText} = render(<Login />)
 // wait until the callback does not throw an error. In this case, that means
 // it'll wait until the element with the text that says "loading..." is gone.
 await wait(() => expect(queryByText(/loading\.\.\./i).not.toBeInTheDOM()))
 getByLabelText('username').value = 'chucknorris'
 // continue doing stuff
})

Read full docs from dom-testing-library

The queries returned from render are scoped to the entire page. Sometimes, there is no guarantee that the text, placeholder, or label you want to query is unique on the page. So you might want to explicitly tell react-render-dom to get an element only within a particular section of the page. within is a helper function for this case.

Example: To get the text 'hello' only within a section called 'messages', you could do:

import {render, within} from 'react-testing-library'
// ...
const {getByTestId} = render(/* stuff */)
const messagesSection = getByTestId('messages')
const hello = within(messagesSection).getByText('hello')

Several APIs accept a TextMatch which can be a string, regex or a function which returns true for a match and false for a mismatch.

See dom-testing-library#textmatch for options.

Examples:

import {render, getByText} from 'react-testing-library'
const {container} = render(<div>Hello World</div>)
// WILL find the div:
// Matching a string:
getByText(container, 'Hello World') // full string match
getByText(container, 'llo Worl', {exact: false}) // substring match
getByText(container, 'hello world', {exact: false}) // ignore case
// Matching a regex:
getByText(container, /World/) // substring match
getByText(container, /world/i) // substring match, ignore case
getByText(container, /^helloworld$/i) // full string match, ignore case
getByText(container, /HelloW?oRlD/i) // advanced regex
// Matching with a custom function:
getByText(container, (content, element) => content.startsWith('Hello'))
// WILL NOT find the div:
getByText(container, 'Goodbye World') // full string does not match
getByText(container, /helloworld/) // case-sensitive regex with different case
// function looking for a span when it's actually a div:
getByText(container, (content, element) => {
 return element.tagName.toLowerCase() === 'span' && content.startsWith('Hello')
})

Each of the get APIs listed in the render section above have a complimentary query API. The get APIs will throw errors if a proper node cannot be found. This is normally the desired effect. However, if you want to make an assertion that an element is not present in the DOM, then you can use the query API instead:

import {render} from 'react-testing-library'
const {queryByText} = render(<Form />)
const submitButton = queryByText('submit')
expect(submitButton).toBeNull() // it doesn't exist

Each of the query APIs have a corresponding queryAll version that always returns an Array of matching nodes. getAll is the same but throws when the array has a length of 0.

import {render} from 'react-testing-library'
const {queryAllByText} = render(<Forms />)
const submitButtons = queryAllByText('submit')
expect(submitButtons).toHaveLength(3) // expect 3 elements
expect(submitButtons[0]).toBeInTheDOM()

We're in the process of moving examples to react-testing-library-examples.

You'll find examples of testing with different libraries in the examples directory. Some included are:

• react-redux
• react-router
• react-context

• Migrating from Enzyme shallow rendering to explicit component mocks

• Confident React

• Test Driven Development with react-testing-library

• Testing React and Web Applications

• Build a joke app with TDD by @mbaranovski

• Build a comment feed with TDD by @iwilsonq

• A clear way to unit testing React JS components using Jest and react-testing-library by Richard Kotze

• Intro to react-testing-library by Chris Noring

• Integration testing in React by Jeffrey Russom

• React-testing-library have fantastic testing 🐐 by Yazan Aabed

• Building a React Tooltip Library by divyanshu013 and metagrover

Feel free to contribute more!

jest.mock('react-transition-group', () => {
 const FakeTransition = jest.fn(({children}) => children)
 const FakeCSSTransition = jest.fn(
 props =>
 props.in ? <FakeTransition>{props.children}</FakeTransition> : null,
 )
 return {CSSTransition: FakeCSSTransition, Transition: FakeTransition}
})
test('you can mock things with jest.mock', () => {
 const {getByTestId, queryByTestId} = render(
 <HiddenMessage initialShow={true} />,
 )
 expect(queryByTestId('hidden-message')).toBeTruthy() // we just care it exists
 // hide the message
 fireEvent.click(getByTestId('toggle-message'))
 // in the real world, the CSSTransition component would take some time
 // before finishing the animation which would actually hide the message.
 // So we've mocked it out for our tests to make it happen instantly
 expect(queryByTestId('hidden-message')).toBeNull() // we just care it doesn't exist
})

expect(queryByTestId('thing-that-does-not-exist')).toBeNull()

const firstLiInDiv = container.querySelector('div li')
const allLisInDiv = container.querySelectorAll('div li')
const rootElement = container.firstChild

const thirdLiInUl = container.querySelector('ul > li:nth-child(3)')

<li data-testid={`item-${item.id}`}>{item.text}</li>

const items = [
 /* your items */
]
const {getByTestId} = render(/* your component with the items */)
const thirdItem = getByTestId(`item-${items[2].id}`)

const firstVersion = container.cloneNode(true)
// Do some changes
snapshotDiff(firstVersion, container.cloneNode(true))

In preparing this project, I tweeted about it and Sune Simonsen took up the challenge. We had different ideas of what to include in the library, so I decided to create this one instead.

The more your tests resemble the way your software is used, the more confidence they can give you.

We try to only expose methods and utilities that encourage you to write tests that closely resemble how your react components are used.

Utilities are included in this project based on the following guiding principles:

1. If it relates to rendering components, it deals with DOM nodes rather than component instances, nor should it encourage dealing with component instances.
2. It should be generally useful for testing individual React components or full React applications. While this library is focused on react-dom, utilities could be included even if they don't directly relate to react-dom.
3. Utility implementations and APIs should be simple and flexible.

At the end of the day, what we want is for this library to be pretty light-weight, simple, and understandable.

Thanks goes to these 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.

See Bugs

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

See Feature Requests

For questions related to using the library, please visit a support community instead of filing an issue on GitHub.

• Spectrum
• Reactiflux on Discord
• Stack Overflow

MIT