react-testing-library
🐐 Simple and complete React DOM testing utilities that encourage good testing practices.
Top Related Projects
Delightful JavaScript Testing.
Fast, easy and reliable testing for anything that runs in a browser.
JavaScript Testing utilities for React
JavaScript API for Chrome and Firefox
☕️ simple, flexible, fun javascript test framework for node.js & the browser
Simple JavaScript testing framework for browsers and node.js
Quick Overview
React Testing Library is a lightweight solution for testing React components. It provides utility functions on top of react-dom and react-dom/test-utils, encouraging better testing practices by working with actual DOM nodes rather than component instances or rendered React elements.
Pros
- Encourages testing components in a way that resembles how users interact with them
- Promotes writing more maintainable tests that are less likely to break with implementation changes
- Simplifies the testing process with a small, intuitive API
- Integrates well with Jest and other testing frameworks
Cons
- May require a mindset shift for developers accustomed to shallow rendering or testing implementation details
- Can be slower than shallow rendering for complex components
- Limited ability to directly test component internals or lifecycle methods
- May require more setup for testing components that rely heavily on context or complex state management
Code Examples
- Basic component rendering and querying:
import { render, screen } from '@testing-library/react';
import MyComponent from './MyComponent';
test('renders hello world', () => {
render(<MyComponent />);
const element = screen.getByText(/hello world/i);
expect(element).toBeInTheDocument();
});
- Testing user interactions:
import { render, screen, fireEvent } from '@testing-library/react';
import Counter from './Counter';
test('increments counter', () => {
render(<Counter />);
const button = screen.getByRole('button', { name: /increment/i });
fireEvent.click(button);
expect(screen.getByText(/count: 1/i)).toBeInTheDocument();
});
- Asynchronous testing:
import { render, screen, waitFor } from '@testing-library/react';
import AsyncComponent from './AsyncComponent';
test('loads and displays data', async () => {
render(<AsyncComponent />);
expect(screen.getByText(/loading/i)).toBeInTheDocument();
await waitFor(() => screen.getByText(/data loaded/i));
expect(screen.getByText(/data loaded/i)).toBeInTheDocument();
});
Getting Started
- Install the library:
npm install --save-dev @testing-library/react @testing-library/jest-dom
- Set up Jest config (if not already done):
{
"setupFilesAfterEnv": ["@testing-library/jest-dom/extend-expect"]
}
- Write your first test:
import { render, screen } from '@testing-library/react';
import App from './App';
test('renders learn react link', () => {
render(<App />);
const linkElement = screen.getByText(/learn react/i);
expect(linkElement).toBeInTheDocument();
});
Competitor Comparisons
Delightful JavaScript Testing.
Pros of Jest
- Comprehensive testing framework with built-in assertion library, mocking, and code coverage
- Supports snapshot testing out of the box
- Parallel test execution for faster performance
Cons of Jest
- Steeper learning curve due to its extensive feature set
- Can be overkill for smaller projects or simple component testing
- Requires more configuration for optimal performance in large projects
Code Comparison
Jest:
test('renders welcome message', () => {
render(<App />);
const welcomeElement = screen.getByText(/Welcome to React/i);
expect(welcomeElement).toBeInTheDocument();
});
React Testing Library:
test('renders welcome message', () => {
render(<App />);
const welcomeElement = screen.getByText(/Welcome to React/i);
expect(welcomeElement).toBeInTheDocument();
});
Key Differences
- React Testing Library focuses on testing components as users would interact with them
- Jest provides a complete testing ecosystem, while React Testing Library is specifically for React components
- React Testing Library encourages more accessible and user-centric tests
- Jest offers more advanced features like mocking and snapshot testing
Use Cases
- Jest: Full-stack applications, complex testing scenarios, projects requiring extensive mocking
- React Testing Library: React component testing, projects prioritizing user-centric testing approaches
Both tools can be used together, with React Testing Library providing the rendering and querying utilities for React components within a Jest test environment.
Fast, easy and reliable testing for anything that runs in a browser.
Pros of Cypress
- Provides an all-in-one testing framework with built-in assertion library and mocking capabilities
- Offers a visual test runner with time-travel debugging and automatic waiting
- Supports end-to-end testing across multiple pages and domains
Cons of Cypress
- Steeper learning curve due to its comprehensive nature and custom API
- Limited to testing in a browser environment, not suitable for unit testing React components in isolation
- Slower test execution compared to React Testing Library's lightweight approach
Code Comparison
React Testing Library:
import { render, fireEvent } from '@testing-library/react';
test('button click', () => {
const { getByText } = render(<Button />);
fireEvent.click(getByText('Click me'));
expect(getByText('Clicked!')).toBeInTheDocument();
});
Cypress:
describe('Button', () => {
it('clicks', () => {
cy.visit('/button');
cy.contains('Click me').click();
cy.contains('Clicked!').should('be.visible');
});
});
While React Testing Library focuses on component-level testing with a simple API, Cypress provides a more comprehensive solution for end-to-end testing with a browser-like environment and powerful debugging tools. The choice between the two depends on the specific testing needs of the project.
JavaScript Testing utilities for React
Pros of Enzyme
- More flexible API for component manipulation and traversal
- Allows shallow rendering for isolated unit testing
- Supports testing of component lifecycle methods
Cons of Enzyme
- Requires more setup and configuration
- Can lead to brittle tests that break with implementation changes
- Less focus on testing from a user's perspective
Code Comparison
Enzyme:
const wrapper = shallow(<MyComponent />);
expect(wrapper.find('.my-class').text()).toBe('Hello');
wrapper.setState({ count: 1 });
wrapper.instance().handleClick();
React Testing Library:
render(<MyComponent />);
expect(screen.getByText('Hello')).toBeInTheDocument();
fireEvent.click(screen.getByRole('button'));
await waitFor(() => expect(screen.getByText('Count: 1')).toBeInTheDocument());
React Testing Library encourages testing components as they're used by end-users, focusing on accessibility and user interactions. Enzyme provides more direct access to component internals, allowing for more granular testing but potentially leading to less maintainable tests. React Testing Library promotes better testing practices aligned with modern React development, while Enzyme offers more flexibility for complex scenarios and legacy codebases.
JavaScript API for Chrome and Firefox
Pros of Puppeteer
- Enables full browser automation, including interactions with non-React elements
- Supports end-to-end testing across multiple pages and domains
- Allows for performance testing and network request interception
Cons of Puppeteer
- Slower test execution compared to React Testing Library
- More complex setup and configuration required
- Less focused on testing React components in isolation
Code Comparison
React Testing Library:
import { render, fireEvent } from '@testing-library/react';
test('button click', () => {
const { getByText } = render(<Button>Click me</Button>);
fireEvent.click(getByText('Click me'));
});
Puppeteer:
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.click('button');
await browser.close();
React Testing Library focuses on testing React components from a user's perspective, while Puppeteer provides broader browser automation capabilities. React Testing Library is more suitable for unit and integration testing of React components, whereas Puppeteer excels in end-to-end testing and scenarios requiring full browser control.
☕️ simple, flexible, fun javascript test framework for node.js & the browser
Pros of Mocha
- More versatile, can be used for testing various JavaScript applications, not limited to React
- Extensive ecosystem with a wide range of plugins and extensions
- Flexible test structure with describe and it blocks for better organization
Cons of Mocha
- Requires additional assertion libraries and mocking tools
- Steeper learning curve for beginners due to more configuration options
- Less focus on testing user interactions and accessibility
Code Comparison
Mocha:
describe('Calculator', () => {
it('should add two numbers correctly', () => {
assert.equal(add(2, 3), 5);
});
});
React Testing Library:
test('renders calculator and performs addition', () => {
render(<Calculator />);
fireEvent.click(screen.getByText('2'));
fireEvent.click(screen.getByText('+'));
fireEvent.click(screen.getByText('3'));
fireEvent.click(screen.getByText('='));
expect(screen.getByTestId('result')).toHaveTextContent('5');
});
The code comparison demonstrates that Mocha focuses on unit testing individual functions, while React Testing Library emphasizes testing components from a user's perspective, simulating interactions and checking the rendered output.
Simple JavaScript testing framework for browsers and node.js
Pros of Jasmine
- More mature and established testing framework with a longer history
- Supports both front-end and back-end JavaScript testing
- Built-in assertion library and mocking capabilities
Cons of Jasmine
- Less focused on React-specific testing scenarios
- Requires more setup and configuration for React component testing
- May encourage testing implementation details rather than user interactions
Code Comparison
Jasmine:
describe('MyComponent', () => {
it('should render correctly', () => {
const component = shallow(<MyComponent />);
expect(component.find('.my-class').length).toBe(1);
});
});
React Testing Library:
test('renders MyComponent correctly', () => {
render(<MyComponent />);
expect(screen.getByText('Expected Text')).toBeInTheDocument();
});
React Testing Library focuses on testing components as users would interact with them, while Jasmine often involves more direct manipulation of component internals. React Testing Library encourages writing more maintainable tests that are less likely to break due to implementation changes, whereas Jasmine tests may be more prone to breaking when component internals are modified.
Convert 
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
React Testing Library
Simple and complete React DOM testing utilities that encourage good testing practices.
Table of Contents
- The problem
- The solution
- Installation
- Examples
- Hooks
- Guiding Principles
- Docs
- Issues
- Contributors
- LICENSE
The problem
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 solution
The React Testing Library is a very lightweight 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. Its
primary guiding principle is:
The more your tests resemble the way your software is used, the more confidence they can give you.
Installation
This module is distributed via npm which is bundled with node and
should be installed as one of your project's devDependencies.
Starting from RTL version 16, you'll also need to install
@testing-library/dom:
npm install --save-dev @testing-library/react @testing-library/dom
or
for installation via yarn
yarn add --dev @testing-library/react @testing-library/dom
This library has peerDependencies listings for react, react-dom and
starting from RTL version 16 also @testing-library/dom.
React Testing Library versions 13+ require React v18. If your project uses an older version of React, be sure to install version 12:
npm install --save-dev @testing-library/react@12
yarn add --dev @testing-library/react@12
You may also be interested in installing @testing-library/jest-dom so you can
use the custom jest matchers.
Suppressing unnecessary warnings on React DOM 16.8
There is a known compatibility issue with React DOM 16.8 where you will see the following warning:
Warning: An update to ComponentName inside a test was not wrapped in act(...).
If you cannot upgrade to React DOM 16.9, you may suppress the warnings by adding the following snippet to your test configuration (learn more):
// this is just a little hack to silence a warning that we'll get until we
// upgrade to 16.9. See also: https://github.com/facebook/react/pull/14853
const originalError = console.error
beforeAll(() => {
console.error = (...args) => {
if (/Warning.*not wrapped in act/.test(args[0])) {
return
}
originalError.call(console, ...args)
}
})
afterAll(() => {
console.error = originalError
})
Examples
Basic Example
// hidden-message.js
import * as React from 'react'
// NOTE: React Testing Library works well with React Hooks and classes.
// Your tests will be the same regardless of how you write your components.
function HiddenMessage({children}) {
const [showMessage, setShowMessage] = React.useState(false)
return (
<div>
<label htmlFor="toggle">Show Message</label>
<input
id="toggle"
type="checkbox"
onChange={e => setShowMessage(e.target.checked)}
checked={showMessage}
/>
{showMessage ? children : null}
</div>
)
}
export default HiddenMessage
// __tests__/hidden-message.js
// these imports are something you'd normally configure Jest to import for you
// automatically. Learn more in the setup docs: https://testing-library.com/docs/react-testing-library/setup#cleanup
import '@testing-library/jest-dom'
// NOTE: jest-dom adds handy assertions to Jest and is recommended, but not required
import * as React from 'react'
import {render, fireEvent, screen} from '@testing-library/react'
import HiddenMessage from '../hidden-message'
test('shows the children when the checkbox is checked', () => {
const testMessage = 'Test Message'
render(<HiddenMessage>{testMessage}</HiddenMessage>)
// query* functions will return the element or null if it cannot be found
// get* functions will return the element or throw an error if it cannot be found
expect(screen.queryByText(testMessage)).toBeNull()
// the queries can accept a regex to make your selectors more resilient to content tweaks and changes.
fireEvent.click(screen.getByLabelText(/show/i))
// .toBeInTheDocument() is an assertion that comes from jest-dom
// otherwise you could use .toBeDefined()
expect(screen.getByText(testMessage)).toBeInTheDocument()
})
Complex Example
// login.js
import * as React from 'react'
function Login() {
const [state, setState] = React.useReducer((s, a) => ({...s, ...a}), {
resolved: false,
loading: false,
error: null,
})
function handleSubmit(event) {
event.preventDefault()
const {usernameInput, passwordInput} = event.target.elements
setState({loading: true, resolved: false, error: null})
window
.fetch('/api/login', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
username: usernameInput.value,
password: passwordInput.value,
}),
})
.then(r => r.json().then(data => (r.ok ? data : Promise.reject(data))))
.then(
user => {
setState({loading: false, resolved: true, error: null})
window.localStorage.setItem('token', user.token)
},
error => {
setState({loading: false, resolved: false, error: error.message})
},
)
}
return (
<div>
<form onSubmit={handleSubmit}>
<div>
<label htmlFor="usernameInput">Username</label>
<input id="usernameInput" />
</div>
<div>
<label htmlFor="passwordInput">Password</label>
<input id="passwordInput" type="password" />
</div>
<button type="submit">Submit{state.loading ? '...' : null}</button>
</form>
{state.error ? <div role="alert">{state.error}</div> : null}
{state.resolved ? (
<div role="alert">Congrats! You're signed in!</div>
) : null}
</div>
)
}
export default Login
// __tests__/login.js
// again, these first two imports are something you'd normally handle in
// your testing framework configuration rather than importing them in every file.
import '@testing-library/jest-dom'
import * as React from 'react'
// import API mocking utilities from Mock Service Worker.
import {rest} from 'msw'
import {setupServer} from 'msw/node'
// import testing utilities
import {render, fireEvent, screen} from '@testing-library/react'
import Login from '../login'
const fakeUserResponse = {token: 'fake_user_token'}
const server = setupServer(
rest.post('/api/login', (req, res, ctx) => {
return res(ctx.json(fakeUserResponse))
}),
)
beforeAll(() => server.listen())
afterEach(() => {
server.resetHandlers()
window.localStorage.removeItem('token')
})
afterAll(() => server.close())
test('allows the user to login successfully', async () => {
render(<Login />)
// fill out the form
fireEvent.change(screen.getByLabelText(/username/i), {
target: {value: 'chuck'},
})
fireEvent.change(screen.getByLabelText(/password/i), {
target: {value: 'norris'},
})
fireEvent.click(screen.getByText(/submit/i))
// just like a manual tester, we'll instruct our test to wait for the alert
// to show up before continuing with our assertions.
const alert = await screen.findByRole('alert')
// .toHaveTextContent() comes from jest-dom's assertions
// otherwise you could use expect(alert.textContent).toMatch(/congrats/i)
// but jest-dom will give you better error messages which is why it's recommended
expect(alert).toHaveTextContent(/congrats/i)
expect(window.localStorage.getItem('token')).toEqual(fakeUserResponse.token)
})
test('handles server exceptions', async () => {
// mock the server error response for this test suite only.
server.use(
rest.post('/api/login', (req, res, ctx) => {
return res(ctx.status(500), ctx.json({message: 'Internal server error'}))
}),
)
render(<Login />)
// fill out the form
fireEvent.change(screen.getByLabelText(/username/i), {
target: {value: 'chuck'},
})
fireEvent.change(screen.getByLabelText(/password/i), {
target: {value: 'norris'},
})
fireEvent.click(screen.getByText(/submit/i))
// wait for the error message
const alert = await screen.findByRole('alert')
expect(alert).toHaveTextContent(/internal server error/i)
expect(window.localStorage.getItem('token')).toBeNull()
})
We recommend using Mock Service Worker library to declaratively mock API communication in your tests instead of stubbing
window.fetch, or relying on third-party adapters.
More Examples
We're in the process of moving examples to the docs site
You'll find runnable examples of testing with different libraries in
the react-testing-library-examples codesandbox.
Some included are:
Hooks
If you are interested in testing a custom hook, check out React Hooks Testing Library.
NOTE: it is not recommended to test single-use custom hooks in isolation from the components where it's being used. It's better to test the component that's using the hook rather than the hook itself. The
React Hooks Testing Libraryis intended to be used for reusable hooks/libraries.
Guiding Principles
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:
- If it relates to rendering components, it deals with DOM nodes rather than component instances, nor should it encourage dealing with component instances.
- 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 toreact-dom. - Utility implementations and APIs should be simple and flexible.
Most importantly, we want React Testing Library to be pretty light-weight, simple, and easy to understand.
Docs
Issues
Looking to contribute? Look for the Good First Issue label.
ð Bugs
Please file an issue for bugs, missing documentation, or unexpected behavior.
ð¡ Feature Requests
Please file an issue to suggest new features. Vote on feature requests by adding a ð. This helps maintainers prioritize what to work on.
â Questions
For questions related to using the library, please visit a support community instead of filing an issue on GitHub.
Contributors
Thanks goes to these people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
LICENSE
Top Related Projects
Delightful JavaScript Testing.
Fast, easy and reliable testing for anything that runs in a browser.
JavaScript Testing utilities for React
JavaScript API for Chrome and Firefox
☕️ simple, flexible, fun javascript test framework for node.js & the browser
Simple JavaScript testing framework for browsers and node.js
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot