Guide · Open source
How to use react-testing-library: install and write your first test
Updated · written with AI from the project's own documentation and checked against our catalogue data
React Testing Library is a small package that lets you write automated tests for React components by working with the DOM the way a user would. This guide shows you how to install it, write a basic test, and understand which queries and versions to use. By the end you will be able to test a React component by what it displays and how it responds to clicks.
React Testing Librarytesting-library/react-testing-library · ★ 19.7k · MIT Install options & downloads Quick start
- 1Check your React version. Confirm your project uses React 18 or newer. If it is older, plan to install version 12 of @testing-library/react.
- 2Install the packages. Run npm install --save-dev @testing-library/react @testing-library/dom, or the yarn equivalent, in your project.
- 3Import the utilities. Import render and screen from @testing-library/react in your test file.
- 4Render the component. Call render with the component you want to test.
- 5Find elements like a user. Use queries such as getByLabelText or getByText to locate the elements a user would see.
- 6Interact and assert. Use fireEvent to simulate interactions, then use expect assertions to check the result.
What React Testing Library is and when to use it
React Testing Library provides light utility functions on top of react-dom and react-dom/test-utils. It is built to encourage tests that resemble how your software is used, so tests keep working when the internals of a component are refactored.
It is a component and DOM testing utility. It is not an end-to-end browser testing tool.
- Good fit: developers writing automated tests for React applications who want behavior-focused tests.
- Not a fit: projects that do not use React, or people who need end-to-end browser testing.
Install React Testing Library with npm or yarn
Install the package as a devDependency using npm or yarn. Starting from version 16, you also need to install @testing-library/dom. The prerequisites are Node.js (npm or yarn) and a React project.
- Versions 13 and newer require React 18.
- If your project uses an older version of React, install version 12 instead.
npm install --save-dev @testing-library/react @testing-library/dom
yarn add --dev @testing-library/react @testing-library/domWrite your first test with render and screen
Component tests usually render the component, find elements the way a user would, interact with them, and check the result. The README example renders a component with a checkbox labelled Show Message and checks that a hidden message appears after the checkbox is clicked.
Use queryBy functions when an element may be absent, since they return null. Use getBy functions when the element must exist, since they throw an error if it cannot be found. You can pass a regular expression to a query to make it more tolerant of small text changes.
- queryBy* returns the element or null.
- getBy* returns the element or throws if it is not found.
- Regular expressions such as /show/i make selectors more resilient to content tweaks.
import '@testing-library/jest-dom'
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>)
expect(screen.queryByText(testMessage)).toBeNull()
fireEvent.click(screen.getByLabelText(/show/i))
expect(screen.getByText(testMessage)).toBeInTheDocument()
})Test forms, async updates and mocked requests
The README's complex example tests a login form that submits to /api/login and shows a role="alert" message on success or failure. The example mocks the network with Mock Service Worker (msw) and its setupServer helper, so the component's fetch call can be tested without a real server.
The example also imports jest-dom for assertions such as toBeInTheDocument. The README notes that jest-dom is recommended but not required.
- Use labels to find form fields, as the login example does with htmlFor and getByLabelText.
- Add jest-dom if you want matchers such as toBeInTheDocument.
Handle the React 16.8 act warning
On React DOM 16.8 you may see a warning that an update was not wrapped in act(...). The README says this is a known compatibility issue. If you cannot upgrade to React DOM 16.9, you can suppress the warning in your test configuration with a snippet that filters that specific message from console.error.
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
})What people use it for
- Testing that a checkbox reveals hidden content in a component.
- Testing a login form's submit behaviour and its success or error messages.
- Checking that a component still behaves the same after its internal code is refactored.
- Writing a suite of component tests for a React 18 application.
Frequently asked questions
How do I install react-testing-library?
Run npm install --save-dev @testing-library/react @testing-library/dom with npm, or yarn add --dev @testing-library/react @testing-library/dom with yarn. Starting from version 16 you need @testing-library/dom as well. Install it in your project's devDependencies.
Does React Testing Library require React 18?
Versions 13 and newer require React 18. If your project uses an older version of React, the README says to install version 12 with @testing-library/react@12.
Is React Testing Library free to use?
The project is released under the MIT licence, as listed on its repository. Check the LICENSE file in the repository for the full terms.
What is the difference between getBy and queryBy?
getBy functions return the element or throw an error if it cannot be found. queryBy functions return the element or null, so they are useful when you want to assert that something is absent.
Can React Testing Library test end-to-end in a browser?
No. The README describes it as a component and DOM testing utility. For end-to-end browser testing, you would need a different tool.
What are alternatives to React Testing Library?
Comparable projects listed for this item include Enzyme, Vitest Browser Mode, Cypress Component Testing and Playwright Component Testing. Each has different goals, so pick based on whether you need component, DOM or browser-level tests.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
React Testing Library suits developers and teams testing React components who want tests that focus on user-visible behaviour and survive refactors. If you do not use React, or you need end-to-end browser tests, pick a different tool such as Cypress or Playwright.
Install options & downloads