React Testing Library: A Practical Guide
Use React Testing Library to verify accessible user behavior and state transitions without coupling tests to component internals. This revised guide emphasizes supported APIs, production tradeoffs, and an upgrade-friendly path without tying the advice to a calendar year.
Modern implementation baseline
Use React Testing Library to verify accessible user behavior and state transitions without coupling tests to component internals.
Prefer function components, current React hooks, accessible interactions, and tests that exercise user-visible behavior. Keep effects for synchronization with external systems instead of using them as a general data-flow mechanism.
Recommended approach
- Prefer semantic queries and user-event interactions.
- Mock network boundaries rather than implementation helpers.
- Keep integration tests focused on valuable workflows.
Production checklist
- Test behavior through roles, labels, and user actions.
- Keep state close to the owner and derive values instead of duplicating them.
- Verify loading, error, empty, and interrupted states.
Authoritative references
Introduction
What is React Testing Library?
React Testing Library is a JavaScript testing utility for React applications that allows developers to write tests that mimic user interactions with their components. It provides a set of utilities that make it easy to query and manipulate rendered components, allowing for thorough testing of UI behaviors.
Why is React Testing Library important?
Testing is an essential part of the software development process, and React Testing Library simplifies the process of testing React components by providing a user-centric approach. It encourages developers to write tests that closely resemble how users interact with the application, resulting in more robust and reliable tests.
Benefits of using React Testing Library
There are several benefits to using React Testing Library for testing React applications. First, it promotes good testing practices by encouraging developers to focus on the user's perspective. This helps ensure that tests are meaningful and relevant to the end user.
Additionally, React Testing Library provides a simple API for querying and manipulating components, making it easy to write tests that are easy to read and understand. It also integrates well with popular testing frameworks such as Jest, allowing for a seamless testing experience.
Setting Up React Testing Library
Installing React Testing Library
To get started with React Testing Library, you need to install it as a development dependency in your project. You can do this by running the following command:
npm install --save-dev @testing-library/react
Configuring React Testing Library
Once React Testing Library is installed, you need to configure it to work with your testing framework. If you are using Jest as your testing framework, no additional configuration is required as React Testing Library works out of the box with Jest.
Writing your first test
To write your first test using React Testing Library, create a new test file with a .test.js or .spec.js extension. In this file, import the necessary functions from React Testing Library and write your test case.
import { render, screen } from '@testing-library/react';
import App from './App';
test('renders the App component', () => {
render(<App />);
const appElement = screen.getByTestId('app');
expect(appElement).toBeInTheDocument();
});
In this example, we render the App component and use the screen.getByTestId function to query for an element with the data-testid attribute set to "app". We then assert that the element is in the document using the expect function.
Testing React Components
Testing component rendering
One of the fundamental aspects of testing React components is ensuring that they render correctly. React Testing Library provides several useful functions for querying and asserting on rendered components.
import { render, screen } from '@testing-library/react';
import Button from './Button';
test('renders a button with the correct text', () => {
render(<Button text="Click me" />);
const buttonElement = screen.getByText('Click me');
expect(buttonElement).toBeInTheDocument();
});
In this example, we render the Button component with a text prop set to "Click me". We then use the screen.getByText function to query for a button element that contains the text "Click me". Finally, we assert that the button element is in the document.
Interacting with components
React Testing Library also provides functions for simulating user interactions with components, such as clicking buttons or entering text into input fields.
import { render, screen, fireEvent } from '@testing-library/react';
import TextInput from './TextInput';
test('updates the input value on change', () => {
render(<TextInput />);
const inputElement = screen.getByLabelText('Enter text:');
fireEvent.change(inputElement, { target: { value: 'Hello, world!' } });
expect(inputElement.value).toBe('Hello, world!');
});
In this example, we render the TextInput component, which renders an input field. We use the screen.getByLabelText function to query for an input element with a matching label text. We then simulate a change event on the input element using the fireEvent.change function and assert that the input value has been updated correctly.
Testing component state and props
React Testing Library provides utilities for testing component state and props. These utilities allow you to query for elements based on their attributes or content, making it easy to assert on the state or props of a component.
import { render, screen } from '@testing-library/react';
import Counter from './Counter';
test('increments the counter on button click', () => {
render(<Counter />);
const counterElement = screen.getByText(/Count: \d+/);
const buttonElement = screen.getByRole('button', { name: /Increment/ });
expect(counterElement).toHaveTextContent('Count: 0');
fireEvent.click(buttonElement);
expect(counterElement).toHaveTextContent('Count: 1');
});
In this example, we render the Counter component, which displays a counter value and an increment button. We use the screen.getByText and screen.getByRole functions to query for the counter element and the increment button, respectively. We then assert that the initial counter value is 0, simulate a click event on the button, and assert that the counter value has been incremented to 1.
Testing React Hooks
React Testing Library is also well-suited for testing React hooks, which are commonly used to manage component state and side effects. React Testing Library provides utilities for testing the useState and useEffect hooks, as well as custom hooks.
Testing useState hook
To test a component that uses the useState hook, you can directly invoke the hook and assert on the resulting state and update function.
import { renderHook, act } from '@testing-library/react-hooks';
import useCounter from './useCounter';
test('increments the counter', () => {
const { result } = renderHook(() => useCounter());
expect(result.current.count).toBe(0);
act(() => {
result.current.increment();
});
expect(result.current.count).toBe(1);
});
In this example, we use renderHook from React Testing Library to render a custom hook called useCounter. We then assert that the initial count value is 0, simulate an increment action using the increment function returned by the hook, and assert that the count value has been updated to 1.
Testing useEffect hook
To test a component that uses the useEffect hook, you can use the render function from React Testing Library and assert on the resulting side effects.
import { render, screen } from '@testing-library/react';
import { rest } from 'msw';
import { setupServer } from 'msw/node';
import UserList from './UserList';
const server = setupServer(
rest.get('/users', (req, res, ctx) => {
return res(ctx.json([{ id: 1, name: 'John Doe' }]));
})
);
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
test('displays a list of users', async () => {
render(<UserList />);
const userElement = await screen.findByText('John Doe');
expect(userElement).toBeInTheDocument();
});
In this example, we use render from React Testing Library to render the UserList component, which makes a GET request to retrieve a list of users and renders them. We use the findByText function to wait for the user element to appear in the document, and then assert that it is in the document.
Testing custom hooks
To test a custom hook, you can use the renderHook function from React Testing Library and assert on the result of invoking the hook.
import { renderHook } from '@testing-library/react-hooks';
import useLocalStorage from './useLocalStorage';
test('stores and retrieves a value in local storage', () => {
const { result } = renderHook(() => useLocalStorage('key', 'initialValue'));
expect(result.current.value).toBe('initialValue');
result.current.setValue('updatedValue');
expect(result.current.value).toBe('updatedValue');
});
In this example, we use renderHook to render a custom hook called useLocalStorage, which stores a value in local storage. We assert that the initial value is set correctly, simulate an update action using the setValue function returned by the hook, and assert that the value has been updated correctly.
Mocking Dependencies
React Testing Library provides utilities for mocking dependencies, such as API calls and external libraries. This allows you to isolate the behavior of your components and focus on testing specific scenarios.
Using jest.mock
To mock a dependency using Jest, you can use the jest.mock function to replace the implementation of the dependency with a mock implementation.
import { render, screen } from '@testing-library/react';
import { getUser } from './api';
import UserDetail from './UserDetail';
jest.mock('./api', () => ({
getUser: jest.fn().mockResolvedValue({ id: 1, name: 'John Doe' }),
}));
test('displays user details', async () => {
render(<UserDetail />);
const userElement = await screen.findByText('John Doe');
expect(userElement).toBeInTheDocument();
});
In this example, we mock the getUser function from the ./api module using jest.mock. We provide a mock implementation that resolves with a user object. We then render the UserDetail component, which calls the getUser function, and assert that the user details are displayed correctly.
Mocking API calls
To mock API calls, you can use a mocking library such as MSW (Mock Service Worker) to intercept and mock network requests.
import { render, screen } from '@testing-library/react';
import { rest } from 'msw';
import { setupServer } from 'msw/node';
import UserList from './UserList';
const server = setupServer(
rest.get('/users', (req, res, ctx) => {
return res(ctx.json([{ id: 1, name: 'John Doe' }]));
})
);
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
test('displays a list of users', async () => {
render(<UserList />);
const userElement = await screen.findByText('John Doe');
expect(userElement).toBeInTheDocument();
});
In this example, we use MSW to intercept and mock a GET request to /users. We define a request handler that returns a JSON response with a list of users. We then render the UserList component, which makes the GET request, and assert that the user element is in the document.
Mocking external libraries
To mock external libraries, you can use the jest.mock function to replace the implementation of the library with a mock implementation.
import { render, screen } from '@testing-library/react';
import moment from 'moment';
import DateComponent from './DateComponent';
jest.mock('moment', () => ({
__esModule: true,
default: jest.fn(() => ({
format: jest.fn().mockReturnValue('sample-date'),
})),
}));
test('displays the formatted date', () => {
render(<DateComponent />);
const dateElement = screen.getByText('sample-date');
expect(dateElement).toBeInTheDocument();
});
In this example, we mock the moment library using jest.mock. We provide a mock implementation that returns an object with a format function that always returns a fixed date string. We then render the DateComponent component, which uses the moment library to format a date, and assert that the formatted date is displayed correctly.
Best Practices for React Testing Library
Writing clean and maintainable tests
To write clean and maintainable tests with React Testing Library, it is important to follow some best practices. First, focus on testing user interactions and behaviors rather than implementation details. This helps ensure that your tests are resilient to changes in the implementation of your components.
Additionally, avoid relying too heavily on implementation details such as CSS classes or DOM structure in your tests. Instead, use semantic queries and queries based on attributes or content to query for elements in your tests. This makes your tests more resilient to changes in the component's markup.
Avoiding common pitfalls
When writing tests with React Testing Library, it is important to avoid common pitfalls that can lead to brittle and unreliable tests. One common pitfall is testing implementation details rather than user behaviors. This can result in tests that break easily when the implementation of the component changes.
Another pitfall is relying too heavily on snapshot testing. While snapshot testing can be useful for capturing the initial state of a component, it should not be used as the sole means of testing. Instead, focus on testing user interactions and behaviors to ensure that your tests are meaningful and relevant to the end user.
Testing edge cases
When testing React components, it is important to test edge cases to ensure that your components handle unexpected inputs or conditions correctly. For example, you might want to test how your component handles empty or null values, or how it behaves when the user enters invalid input.
To test edge cases, you can use the same techniques and utilities provided by React Testing Library, such as querying for elements based on their attributes or content, simulating user interactions, and asserting on the expected behavior or state of the component.
Conclusion
In this tutorial, we explored React Testing Library and its capabilities for testing React components and hooks. We covered the basics of setting up React Testing Library, testing component rendering and interactions, testing component state and props, testing React hooks, mocking dependencies, and best practices for writing clean and maintainable tests.
React Testing Library provides a user-centric approach to testing React applications, making it easier to write tests that closely resemble how users interact with the application. By following the best practices outlined in this tutorial, you can ensure that your tests are robust, reliable, and meaningful to the end user.