Chapter 20: Testing React Components with React Testing Library and Jest

Welcome back, intrepid developer! You’ve learned to build amazing React components, manage state, handle side effects, and even optimize performance. But how do you ensure your creations are robust, bug-free, and behave exactly as you intend, especially as your application grows and evolves? The answer, my friend, is testing!

In this chapter, we’re going to dive headfirst into the world of testing React components. We’ll explore two powerful tools that form the backbone of modern React testing: Jest as our testing framework and React Testing Library (RTL) for interacting with our components. Our goal isn’t just to write tests, but to understand why we test, what makes a good test, and how to write tests that give us confidence and peace of mind. By the end, you’ll be equipped to write effective, user-centric tests for your React applications, ensuring they stand the test of time.

This chapter assumes you’re comfortable with creating React components, handling props, managing state, and basic event handling, as covered in previous chapters. We’ll build upon those foundations to verify their correct behavior.

Why Do We Test Our Code? The Confidence Multiplier!

Before we even touch a testing tool, let’s ponder the “why.” Why bother writing tests when you could be building new features?

Bug Detection: This is the most obvious one! Tests catch bugs early, often before they even reach a user. It’s much cheaper and easier to fix a bug discovered by a test than one reported by a customer in production.
Confidence in Refactoring: Imagine you need to rewrite a component or change its internal logic. If you have a solid suite of tests, you can make those changes with confidence, knowing that if you break existing functionality, your tests will immediately tell you. It’s like having a safety net!
Documentation: Well-written tests can serve as executable documentation. By looking at a test, another developer (or even your future self!) can quickly understand how a component is expected to behave.
Prevent Regressions: A “regression” is when a new change introduces a bug into previously working code. Tests prevent this by ensuring that old features continue to function correctly after new code is added.
Better Design: The act of writing testable code often encourages better architectural design. Components become more modular, focused, and easier to reason about when you consider how they will be tested.

In essence, testing isn’t an overhead; it’s an investment that pays dividends in quality, stability, and developer velocity.

Introducing Jest and React Testing Library

For modern React applications, the combination of Jest and React Testing Library is the gold standard. Let’s break down what each tool does:

Jest: The Testing Maestro

Jest is a delightful JavaScript testing framework developed by Facebook (now Meta). Think of Jest as the orchestrator of your tests. It provides:

A Test Runner: It finds your test files (e.g., *.test.js or *.spec.js) and executes them.
An Assertion Library: It gives you methods like expect(value).toBe(anotherValue) to check if your code behaves as expected.
Mocking Capabilities: It allows you to replace parts of your code (like API calls or external modules) with “mock” versions during tests, so you can test your component in isolation without actual network requests.
Code Coverage: It can tell you what percentage of your code is covered by tests.

Jest is powerful, fast, and comes with a fantastic developer experience.

React Testing Library (RTL): User-Centric Testing

While Jest provides the framework, React Testing Library (RTL) provides a set of utilities specifically designed for testing React components. But what makes RTL special? Its core philosophy:

“The more your tests resemble the way your software is used, the more confidence they can give you.” — Kent C. Dodds, Creator of React Testing Library

This means RTL encourages you to test your components as a user would interact with them. Instead of peeking at a component’s internal state or implementation details (like a specific prop name or internal function), you interact with the rendered output of your component using queries that mimic how a user would find elements on the page (e.g., by text, by label, by role).

Why is this important? If you test implementation details, your tests become brittle. A small refactor of your component’s internals (which shouldn’t affect its user-facing behavior) would break your tests. By focusing on user experience, your tests become more resilient and provide more confidence.

Setting Up Your Testing Environment

If you’ve initialized your React project using modern tools like Create React App (CRA) or Vite, you’re likely already set up with Jest and React Testing Library! Both tools come pre-configured with a robust testing environment.

Create React App (CRA): Includes react-scripts which bundles Jest and RTL.
Vite: Often uses Vitest as a default test runner, which is Jest-compatible, and RTL works seamlessly with it. For this chapter, we’ll assume a Jest environment, but the RTL APIs are largely identical.

Verification for 2026-01-31:

Let’s ensure we have the necessary packages. Open your project’s package.json file. You should see dependencies similar to these. If not, you can install them:

# Using npm
npm install --save-dev react@^19.0.0 react-dom@^19.0.0 @testing-library/react@^14.0.0 @testing-library/jest-dom@^7.0.0 @testing-library/user-event@^15.0.0 jest@^30.0.0 jest-environment-jsdom@^30.0.0

# Or using yarn
yarn add --dev react@^19.0.0 react-dom@^19.0.0 @testing-library/react@^14.0.0 @testing-library/jest-dom@^7.0.0 @testing-library/user-event@^15.0.0 jest@^30.0.0 jest-environment-jsdom@^30.0.0

react and react-dom: We’re targeting React v19.0.0 (or newer) for 2026.
@testing-library/react: Version 14.0.0+ is the latest stable. This provides the render method and queries.
@testing-library/jest-dom: Version 7.0.0+ is the latest stable. This package provides custom Jest matchers (like toBeInTheDocument()) that make assertions much more readable.
@testing-library/user-event: Version 15.0.0+ is the latest stable. This library simulates realistic user interactions (typing, clicking, etc.) more accurately than fireEvent.
jest: Version 30.0.0+ is anticipated for 2026. This is our test runner and assertion library.
jest-environment-jsdom: Version 30.0.0+ is anticipated for 2026. This provides a browser-like environment for your tests to run in.

Important Note for @testing-library/jest-dom: To make the custom matchers available in all your tests, you need to import them once. If you’re using CRA, this is usually handled in src/setupTests.js. For Vite or manual setups, you might need to configure Jest to load this file.

Here’s what src/setupTests.js (or a similar configuration file) typically looks like:

// src/setupTests.js
// This file is automatically run before each test file.
import '@testing-library/jest-dom';

This single line is crucial as it extends Jest’s expect function with powerful matchers like toBeInTheDocument(), toHaveTextContent(), toBeVisible(), and many more.

Step-by-Step Implementation: Testing a Simple Button Component

Let’s get our hands dirty! We’ll start by creating a very simple Button component and then write our first tests for it.

1. Create the Button Component

First, let’s create our component.

Create a new file: src/components/Button/Button.jsx

// src/components/Button/Button.jsx
import React from 'react';
import PropTypes from 'prop-types'; // Good practice for prop validation

const Button = ({ onClick, children, disabled = false }) => {
  return (
    <button onClick={onClick} disabled={disabled}>
      {children}
    </button>
  );
};

Button.propTypes = {
  onClick: PropTypes.func.isRequired,
  children: PropTypes.node.isRequired,
  disabled: PropTypes.bool,
};

export default Button;

Explanation:

This is a functional React component named Button.
It accepts three props:
- onClick: A function to be called when the button is clicked. It’s marked as isRequired.
- children: The content to be displayed inside the button (e.g., text, an icon). Also isRequired.
- disabled: A boolean to control if the button is interactable. It defaults to false.
We’ve added PropTypes for basic type checking, which is a good practice for component robustness.

2. Create the Test File

Now, let’s create a corresponding test file right next to our component. This is a common convention that makes tests easy to find.

Create a new file: src/components/Button/Button.test.jsx

// src/components/Button/Button.test.jsx
import React from 'react';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import Button from './Button';

// A placeholder function for our onClick prop
const noop = () => {};

describe('Button Component', () => {
  // Our first test!
  test('renders with default text and is enabled', () => {
    // 1. Arrange: Set up the component for testing
    render(<Button onClick={noop}>Click Me</Button>);

    // 2. Act (Implicit): The component has rendered. Now we interact/query.
    // screen.getByText is a query that finds an element by its text content.
    const buttonElement = screen.getByText('Click Me');

    // 3. Assert: Check if the button is in the document and is not disabled
    expect(buttonElement).toBeInTheDocument();
    expect(buttonElement).not.toBeDisabled();
  });
});

Explanation - Step-by-Step:

import React from 'react';: Standard React import.
import { render, screen } from '@testing-library/react';:
- render: This function takes a React element (your component) and renders it into a virtual DOM environment provided by jsdom. It’s like rendering your component to the browser, but in memory.
- screen: This object provides access to all the queries that React Testing Library offers. We’ll use it to find elements in the rendered component.
import userEvent from '@testing-library/user-event';: We’ll use this soon to simulate user interactions.
import Button from './Button';: Import the component we want to test.
const noop = () => {};: A simple empty function. We need to pass a function to onClick because it’s isRequired in our propTypes. For tests where we don’t care about its actual execution, a noop is perfect.
describe('Button Component', () => { ... });:
- describe is a Jest function that groups related tests together. It makes your test output more organized.
- The first argument is a string description, and the second is a callback function containing your tests.
test('renders with default text and is enabled', () => { ... });:
- test (or it) is a Jest function that defines a single test case.
- The first argument is a descriptive string of what this test is verifying.
- The second is a callback function containing the actual test logic.
render(<Button onClick={noop}>Click Me</Button>);:
- This is the “Arrange” phase. We render our Button component, passing the required onClick prop and “Click Me” as its children.
const buttonElement = screen.getByText('Click Me');:
- This is part of the “Act” phase (implicitly, we’re querying the rendered component).
- screen.getByText is a query function from RTL. It searches the entire document (the virtual DOM) for an element whose text content exactly matches ‘Click Me’.
- If it finds the element, it returns it. If it doesn’t, it throws an error, causing the test to fail.
- Pro Tip: RTL offers different types of queries:
  - getBy...: Returns the element or throws an error. Good for elements expected to be present immediately.
  - queryBy...: Returns the element or null. Good for checking if an element is not present.
  - findBy...: Returns a Promise that resolves with the element or rejects if not found after a timeout. Essential for asynchronous elements (e.g., data fetched from an API).
  - Each type has variants like getByRole, getByLabelText, getByPlaceholderText, getByText, getByDisplayValue, and getByTestId.
  - Always prefer queries that mimic user interaction: getByRole > getByLabelText > getByPlaceholderText > getByText > getByDisplayValue > getByTestId. We use getByText here because the button’s primary identifier is its text content.
expect(buttonElement).toBeInTheDocument();:
- This is the “Assert” phase. expect is a Jest function that creates an assertion.
- toBeInTheDocument() is a custom matcher provided by @testing-library/jest-dom. It checks if the element exists within the document (virtual DOM).
expect(buttonElement).not.toBeDisabled();:
- Another matcher, toBeDisabled(), checks the disabled attribute of the element. We expect it not to be disabled by default.

3. Run Your Tests

To run your tests, open your terminal in the project root and execute:

npm test
# or
yarn test

Jest will run, find your Button.test.jsx file, and execute the test. You should see output indicating that your test passed successfully!

PASS src/components/Button/Button.test.jsx
  Button Component
    ✓ renders with default text and is enabled (xx ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        X.XXX s

Fantastic! You’ve just written and run your first React component test.

4. Testing Props and User Interactions

Let’s expand our test file to cover more scenarios, specifically how the button behaves when disabled and when clicked.

Update src/components/Button/Button.test.jsx:

// src/components/Button/Button.test.jsx
import React from 'react';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event'; // Don't forget this import!
import Button from './Button';

const noop = () => {};

describe('Button Component', () => {
  test('renders with default text and is enabled', () => {
    render(<Button onClick={noop}>Click Me</Button>);
    const buttonElement = screen.getByText('Click Me');
    expect(buttonElement).toBeInTheDocument();
    expect(buttonElement).not.toBeDisabled();
  });

  test('renders with different text passed via children prop', () => {
    render(<Button onClick={noop}>Submit Form</Button>);
    const buttonElement = screen.getByText('Submit Form');
    expect(buttonElement).toBeInTheDocument();
  });

  test('is disabled when the disabled prop is true', () => {
    render(<Button onClick={noop} disabled={true}>Disabled Button</Button>);
    const buttonElement = screen.getByText('Disabled Button');
    expect(buttonElement).toBeDisabled();
  });

  test('calls the onClick handler when clicked', async () => {
    // 1. Arrange: Create a mock function for onClick
    const mockOnClick = jest.fn(); // Jest's powerful mocking function

    render(<Button onClick={mockOnClick}>Clickable Button</Button>);
    const buttonElement = screen.getByText('Clickable Button');

    // 2. Act: Simulate a user clicking the button
    // userEvent.click is asynchronous, so we need to await it
    await userEvent.click(buttonElement);

    // 3. Assert: Check if the mock function was called
    expect(mockOnClick).toHaveBeenCalledTimes(1);
  });

  test('does not call the onClick handler when disabled and clicked', async () => {
    const mockOnClick = jest.fn();

    render(<Button onClick={mockOnClick} disabled={true}>Disabled Click</Button>);
    const buttonElement = screen.getByText('Disabled Click');

    // Attempt to click the disabled button
    await userEvent.click(buttonElement);

    // Assert that the onClick handler was NOT called
    expect(mockOnClick).not.toHaveBeenCalled();
    expect(mockOnClick).toHaveBeenCalledTimes(0); // Alternative way to assert
  });
});

New Explanations:

test('renders with different text passed via children prop', ...): This test confirms that our Button component correctly displays whatever text is passed as its children prop.
test('is disabled when the disabled prop is true', ...): This test verifies that if we pass disabled={true}, the button element correctly receives the disabled attribute, which we check with toBeDisabled().
test('calls the onClick handler when clicked', async () => { ... });:
- const mockOnClick = jest.fn();: This is a Jest mock function. It’s a special function that allows us to track how it’s called (e.g., how many times, with what arguments). It’s perfect for testing callbacks like onClick without actually needing a full implementation.
- await userEvent.click(buttonElement);: userEvent is a library built on top of fireEvent but provides a more realistic simulation of user interactions. For example, userEvent.click will not only fire a click event but also pointerDown, pointerUp, mouseDown, mouseUp, focus, etc., just like a real browser. Since these interactions can involve microtasks, it’s best practice to await userEvent actions.
- expect(mockOnClick).toHaveBeenCalledTimes(1);: This Jest matcher checks if our mockOnClick function was called exactly once. This confirms our button’s onClick prop is correctly wired up.
test('does not call the onClick handler when disabled and clicked', ...): This test combines the disabled prop with a click simulation to ensure that clicking a disabled button does not trigger the onClick handler. This is a critical piece of behavior to verify.

Run npm test again, and you should see all your tests pass!

A Note on `screen` and its Queries

screen is your primary tool for finding elements in your rendered component. Here’s a quick cheat sheet for common queries, ordered by preference (most accessible first):

getByRole(role, { name }): The best way to find elements. Users of assistive technologies navigate by roles (e.g., button, link, heading, checkbox). The name option allows finding specific instances, often derived from text content or aria-label.
- Example: screen.getByRole('button', { name: /click me/i })
getByLabelText(text): Finds elements associated with a <label> element.
- Example: screen.getByLabelText('Username') for <label for="username">Username</label><input id="username" />
getByPlaceholderText(text): Finds input/textarea by its placeholder attribute.
getByText(text): Finds any element that has the given text content. Useful for buttons, paragraphs, headings.
getByDisplayValue(value): Finds input, textarea, or select elements by their current value.
getByAltText(text): Finds <img> elements by their alt attribute.
getByTitle(text): Finds elements by their title attribute.
getByTestId(id): The least preferred. Use only when other semantic queries are not possible. Requires adding data-testid="my-id" to your elements.

Always strive to use queries that reflect how a user would perceive or interact with your component. This makes your tests more robust and improves accessibility.

Mini-Challenge: Test a Counter Component

Alright, it’s your turn to apply what you’ve learned!

Challenge: Create a simple Counter component that displays a number and has two buttons: one to increment the number and one to decrement it. Then, write tests for this Counter component using Jest and React Testing Library.

Steps:

Create src/components/Counter/Counter.jsx.
Implement the Counter component with:
- A state variable for the count, initialized to 0.
- A p tag or div to display the current count.
- An “Increment” button.
- A “Decrement” button.
Create src/components/Counter/Counter.test.jsx.
Write tests to verify:
- The counter renders with an initial value of 0.
- Clicking the “Increment” button increases the count by 1.
- Clicking the “Decrement” button decreases the count by 1.
- (Bonus) The count does not go below 0.

Hint:

Remember to use userEvent.click() for simulating button clicks.
Use screen.getByText() or screen.getByRole('button', { name: /increment/i }) to find your buttons.
You’ll need await for userEvent actions.
To check the displayed count, you can use screen.getByText('0'), screen.getByText('1'), etc., or screen.getByText(/^Current Count: \d+$/).

What to Observe/Learn: You’ll solidify your understanding of rendering components for testing, finding elements using various queries, and simulating user interactions to test state changes. You’ll also practice setting up your test files and assertions.

Common Pitfalls & Troubleshooting

Testing can sometimes feel tricky, but most issues have common roots. Here are a few pitfalls and how to navigate them:

Forgetting await for userEvent or findBy queries:

Pitfall: You might see errors like “act(…)” warnings, or your assertions might fail because the UI hasn’t updated yet. userEvent and findBy are asynchronous.
Troubleshooting: Always remember to use async on your test callback and await any userEvent action (e.g., await userEvent.click(...)) or findBy query (e.g., await screen.findByText(...)).

// ❌ WRONG
test('clicks button', () => {
  render(<MyButton />);
  userEvent.click(screen.getByText('Click Me'));
  expect(screen.getByText('Clicked!')).toBeInTheDocument(); // Might fail due to async update
});

// ✅ CORRECT
test('clicks button', async () => { // Make test async
  render(<MyButton />);
  await userEvent.click(screen.getByText('Click Me')); // Await userEvent
  expect(screen.getByText('Clicked!')).toBeInTheDocument();
});

Testing Implementation Details Instead of User Behavior:
- Pitfall: Writing tests that rely on a component’s internal state, prop drilling, or specific CSS class names. When you refactor the component’s internal logic, these tests break even if the user experience remains the same.
- Troubleshooting: Re-read the RTL guiding principle: “The more your tests resemble the way your software is used, the more confidence they can give you.” Prioritize queries like getByRole, getByLabelText, getByText. Avoid getByTestId unless absolutely necessary, and never directly inspect component.props or component.state in RTL. Focus on what the user sees and does.
Not Cleaning Up Between Tests:
- Pitfall: If you render components in one test and don’t clean them up, they might affect subsequent tests, leading to flaky failures (tests that pass sometimes and fail others).
- Troubleshooting: React Testing Library’s render function automatically cleans up the DOM after each test by default (since @testing-library/react v9.0.0+). However, if you’re doing manual DOM manipulation or using older versions, you might need cleanup from @testing-library/react. You can add afterEach(cleanup) to your test file if you encounter issues, though it’s generally not required for basic RTL usage anymore.
Accessibility Concerns in Tests:
- Pitfall: Using getByTestId everywhere. This makes your tests less readable and doesn’t encourage accessible component design.
- Troubleshooting: As mentioned, use getByRole and getByLabelText first. This forces you to think about the accessibility of your components early on. If your component isn’t accessible, it’s harder to test with RTL’s preferred queries, which is a good signal to improve your component’s accessibility.

Summary

Phew! You’ve just taken a significant leap in your React journey by embracing testing. Here’s a quick recap of what we covered:

Why Test? We learned that testing boosts confidence, catches bugs, aids refactoring, prevents regressions, and encourages better code design.
Jest & React Testing Library: We distinguished between Jest (the test runner, assertion, and mocking framework) and React Testing Library (the user-centric utility for rendering and querying React components).
Setup: We verified the necessary packages (@testing-library/react, @testing-library/jest-dom, user-event, jest) and the importance of setupTests.js.
Core Testing Flow: We followed the “Arrange, Act, Assert” pattern.
Rendering Components: We used render(<YourComponent />) to bring our components into the test environment.
Querying Elements: We explored screen and its powerful queries like getByText, getByRole, getByLabelText, emphasizing user-centric approaches.
Simulating Interactions: We leveraged userEvent.click() to realistically simulate user actions.
Making Assertions: We used Jest’s expect() combined with @testing-library/jest-dom matchers like toBeInTheDocument(), not.toBeDisabled(), and Jest’s toHaveBeenCalledTimes() for mock functions.
Mocking: We saw how jest.fn() helps us test callbacks in isolation.
Asynchronous Testing: The importance of await for userEvent and findBy queries.
Common Pitfalls: We discussed avoiding common mistakes like missing await, testing implementation details, and neglecting accessibility.

You now have the foundational knowledge to start writing effective, maintainable tests for your React components. This skill is invaluable for any professional React developer!

What’s Next?

In the upcoming chapters, we’ll continue to build on our testing knowledge. We’ll explore more advanced topics such as:

Mocking APIs and External Modules: How to test components that interact with networks or third-party libraries.
Context and Reducers Testing: Strategies for testing components that rely on React Context or useReducer.
Integration Testing: Testing how multiple components work together.
End-to-End (E2E) Testing: A brief overview of testing full user flows across your entire application.

Keep practicing, keep building, and keep testing!

References

React Testing Library Official Documentation: The definitive guide for render, screen, queries, and best practices.
- https://testing-library.com/docs/react-testing-library/intro/
Jest Official Documentation: Comprehensive resource for Jest’s API, configuration, and advanced features.
- https://jestjs.io/docs/getting-started
@testing-library/jest-dom GitHub Repository: Details on the custom matchers provided by this library.
- https://github.com/testing-library/jest-dom
@testing-library/user-event GitHub Repository: Information on simulating realistic user interactions.
- https://github.com/testing-library/user-event
React Official Documentation - Testing Components: React’s own guidance on testing.
- https://react.dev/learn/testing-react-components

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.