Logo
Tutorials Articles Code Playground Tools
Sign In Get Started
Module: Testing React Applications

React Testing Library

Testing React Applications with React Testing Library

React Testing Library (RTL) is a popular testing library for React components. It encourages writing tests that focus on how users interact with your components, rather than focusing on implementation details. This leads to more robust and maintainable tests.

Why React Testing Library?

  • User-Focused: RTL prioritizes testing from the user's perspective. You interact with components as a user would – by finding elements based on their role, text content, or labels.
  • Avoids Implementation Details: It discourages testing internal component state or implementation details. This makes your tests less brittle and less likely to break when you refactor your code.
  • Accessibility Focused: RTL promotes writing accessible components by encouraging you to use semantic HTML and ARIA attributes. Finding elements by role (e.g., role="button") inherently encourages accessibility.
  • Simple and Intuitive API: RTL provides a clean and easy-to-learn API.
  • Works with Popular Test Runners: RTL integrates seamlessly with popular test runners like Jest and Mocha.

Setting up React Testing Library

  1. Install Dependencies:

    npm install --save-dev @testing-library/react @testing-library/jest-dom
# or
yarn add --dev @testing-library/react @testing-library/jest-dom
    • @testing-library/react: The core RTL library.
    • @testing-library/jest-dom: Provides helpful Jest matchers for asserting DOM elements.

  2. Configure Jest (if using Jest):

    Add the following to your jest.config.js or jest.config.ts:

    // jest.config.js
module.exports = {
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.js'], // Or your setup file path
};

    Create a src/setupTests.js (or similar) file and add:

    // src/setupTests.js
import '@testing-library/jest-dom';

Core Concepts & API

  • render: Renders a React component into a container in a testing environment. Returns an object with methods for querying the rendered component.

  • screen: A global object provided by RTL that allows you to query the rendered component without needing to explicitly return the result of render. It's generally preferred for cleaner tests.

  • Querying: RTL provides various querying methods to find elements in the DOM. These are categorized by how specific they are:

    • getBy...: Returns the element if it exists. Throws an error if the element is not found. Use for elements you expect to be present.
    • findBy...: Returns a promise that resolves with the element when it appears in the DOM. Useful for asynchronous updates. Throws an error if the element is never found.
    • queryBy...: Returns the element if it exists, otherwise returns null. Useful for asserting that an element does not exist.

    Common Querying Methods:

    • getByRole(role, {name, exact, ...}): Finds an element by its ARIA role (e.g., 'button', 'link', 'heading'). name allows you to filter by text content. exact requires an exact text match.
    • getByText(text, {exact, normalize, ...}): Finds an element by its text content. exact requires an exact match. normalize allows you to normalize whitespace.
    • getByLabelText(text, {selector}): Finds an element associated with a label. Useful for form elements.
    • getByPlaceholderText(text): Finds an input element by its placeholder text.
    • getByAltText(text): Finds an image element by its alt text.
    • getByTitle(text): Finds an element by its title attribute.
    • getByTestId(id): Finds an element by its data-testid attribute. Use sparingly – it's a last resort when other queries aren't possible.

  • fireEvent: Simulates user events on DOM elements.

    • fireEvent.click(element)
    • fireEvent.change(element, { target: { value: 'new value' } })
    • fireEvent.input(element, { target: { value: 'new value' } })
    • fireEvent.keyDown(element, { key: 'Enter' })
    • fireEvent.submit(formElement)

  • waitFor: Waits for a condition to be met before continuing the test. Useful for asynchronous updates or animations.

Example Test

import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import MyComponent from './MyComponent';

test('renders learn react link', () => {
  render(<MyComponent />);
  const linkElement = screen.getByText(/learn react/i);
  expect(linkElement).toBeInTheDocument();
});

test('updates counter on button click', async () => {
  render(<MyComponent />);
  const buttonElement = screen.getByRole('button', { name: /increment/i });
  fireEvent.click(buttonElement);

  // Wait for the counter to update
  await waitFor(() => {
    const counterElement = screen.getByText(/count: 1/i);
    expect(counterElement).toBeInTheDocument();
  });
});

Best Practices

  • Prioritize getByRole: Use getByRole whenever possible to find elements based on their semantic meaning.
  • Use getByText with Caution: Be mindful of text content that might change. Consider using getByRole with a name prop instead.
  • Avoid getByTestId: Use data-testid attributes only as a last resort. They tightly couple your tests to your implementation.
  • Test User Interactions: Focus on testing how users interact with your components, not internal state.
  • Keep Tests Small and Focused: Each test should verify a single behavior.
  • Use waitFor for Asynchronous Updates: Ensure your tests wait for asynchronous operations to complete before making assertions.
  • Write Accessible Components: RTL encourages you to write accessible components, which benefits all users.

Resources