REACT (https://www.kirupa.com/react/index.htm)

BOOK (https://www.amazon.com/exec/obidos/ASIN/0134546318/kirupacom)

Testing React Apps

by kirupa (https://www.kirupa.com/me/index.htm) | filed under Learning React (https://www.kirupa.com/react/index.htm)

You build a component, click around in the browser, and it works. A week later you change something small in a totally different part of your app, and the component quietly breaks. You don't find out until somebody tells you. Sound familiar?

This is the problem automated tests solve. A test is a little program that uses your component the way a person would (it clicks, types, and reads what is on the screen) and then tells you if the result was what you expected. You write it once, and from then on, the computer does the clicking around for you every time you make a change.

In this tutorial, we'll set up testing in a Vite-based React project using Vitest (the test runner) and React Testing Library (the tools for rendering components and finding things in them). Then we'll write tests for a counter, a todo list, a form, and a component that loads data. All of the tests you see here were run for real, and the output you will see is the real output.

What We Are Using

Testing in React involves a few separate pieces, and it helps to know what each one does before we install them:

- Vitest is the test runner. It finds your test files, runs them, and reports what passed and what failed. It is built to work with Vite, so it reuses the same configuration and handles JSX without extra setup. If you have used Jest before, the functions are nearly identical.
- jsdom pretends to be a browser. Your tests run in Node, which has no document or window. jsdom provides a fake version of them so that React has something to render into.
- React Testing Library gives you render to put a component on that fake page, and screen to look for things in it.
- user-event simulates what a person does, like clicking and typing, in a realistic way.
- jest-dom adds readable checks like toBeInTheDocument() and toBeDisabled(). Despite the name, it works great with Vitest.

React Testing Library follows a philosophy that is worth knowing about now: test what the user sees, not how your component is built. You find a button by its name, not by its CSS class or the name of a state variable. That way, you can rewrite how a component works inside (swap useState for useReducer, say) and your tests keep passing, as long as the component still behaves the same. A test that breaks every time you refactor is more of a chore than a help.

Setting Up

We'll start with a regular Vite React project. If you don't have one, the steps are in setting up your React environment (https://www.kirupa.com/react/setting_up_react_environment.htm). You'll need a recent version of Node for this. The version of Vitest I used wants Node 22.12 or newer.

First, install everything as dev dependencies, since they are only used while you are developing:

npm install -D vitest @testing-library/react @testing-library/dom @testing-library/jest-dom @testing-library/user-event jsdom

Yes, @testing-library/dom is a separate item on that list. React Testing Library needs it, but expects you to install it yourself, and you'll get a confusing error if you skip it.

Next, open vite.config.js and tell Vitest to use jsdom and where to find a setup file. You're adding the test section to the config you already have:

import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    setupFiles: "./src/setupTests.js",
  },
});

Then create that setup file, src/setupTests.js. This file runs before your tests do:

import "@testing-library/jest-dom/vitest";
import { cleanup } from "@testing-library/react";
import { afterEach } from "vitest";

afterEach(() => {
  cleanup();
});

The first line adds the jest-dom checks to Vitest. The rest is something you should not skip: after each test, we tell React Testing Library to remove everything it rendered. Test libraries usually do this automatically, but Vitest doesn't expose its test functions as globals by default, so React Testing Library can't hook in on its own. I tested what happens without it. The components from earlier tests pile up on the page, and then you get failures like expected [ <p></p>, <p></p> ] to have a length of 1 but got 2. If you ever see a test fail because it found too many of something, this is the first thing to check.

Finally, add a script to package.json:

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "test": "vitest"
}

Now npm test starts Vitest. When you run it in your terminal, it stays running in watch mode. It re-runs the affected tests every time you save a file, which is wonderful while you are working. If you just want one run that exits, use npx vitest run.

Your First Test

Let's test a simple component. Here is a counter:

import { useState } from "react";

function Counter({ initialCount = 0 }) {
  const [count, setCount] = useState(initialCount);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count - 1)}>Decrement</button>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

export default Counter;

Test files go next to the component and end in .test.jsx, which is how Vitest finds them. Here is Counter.test.jsx with the first two tests:

import { render, screen } from "@testing-library/react";
import { describe, expect, test } from "vitest";
import Counter from "./Counter";

describe("Counter", () => {
  test("starts at zero", () => {
    render(<Counter />);

    expect(screen.getByText("Count: 0")).toBeInTheDocument();
  });

  test("starts at the initialCount it is given", () => {
    render(<Counter initialCount={10} />);

    expect(screen.getByText("Count: 10")).toBeInTheDocument();
  });
});

There are four things going on in this file:

- describe groups related tests under a name. It is optional, but it keeps the output tidy.
- test (you can also write it) defines a single test. The first argument is a plain English description, and the second is the function that does the work.
- render draws the component onto the fake page.
- expect(...) followed by a check, like toBeInTheDocument(), is the assertion. If it isn't true, the test fails.

The test is shaped like a story: set things up, do something, check the result. You'll see that pattern again and again.

Simulating Clicks and Typing

Components that don't respond to anything aren't very interesting. To click a button, we use user-event. Add this third test inside the same describe (and add the import at the top):

import userEvent from "@testing-library/user-event";

test("goes up and down when the buttons are clicked", async () => {
  const user = userEvent.setup();
  render(<Counter />);

  await user.click(screen.getByRole("button", { name: "Increment" }));
  await user.click(screen.getByRole("button", { name: "Increment" }));
  expect(screen.getByText("Count: 2")).toBeInTheDocument();

  await user.click(screen.getByRole("button", { name: "Decrement" }));
  expect(screen.getByText("Count: 1")).toBeInTheDocument();
});

A few details matter here. The test function is now async, because everything user-event does returns a promise, so you must await it. You call userEvent.setup() once at the start of each test and use the user it gives you. And look at how we find the buttons:

screen.getByRole("button", { name: "Increment" })

That means "find me the thing a screen reader would call a button, and whose label is Increment." We'll talk more about why that is the preferred way to find things in a bit.

Now let's run the tests. Here is what I got from npx vitest run in the project, with all four test files from this tutorial in place:

 ✓ src/HeroList.test.jsx (2 tests) 82ms
 ✓ src/Counter.test.jsx (3 tests) 108ms
 ✓ src/SubscribeForm.test.jsx (2 tests) 178ms
 ✓ src/TodoList.test.jsx (5 tests) 234ms

 Test Files  4 passed (4)
      Tests  12 passed (12)

Green checkmarks are lovely. But a test that has never failed hasn't proven that it can catch anything, so let's break something on purpose. I changed the Increment button to add 2 instead of 1:

<button onClick={() => setCount(count + 2)}>Increment</button>

And the test caught it:

FAIL  src/Counter.test.jsx > Counter > goes up and down when the buttons are clicked
TestingLibraryElementError: Unable to find an element with the text: Count: 2.

<body>
  <div>
    <div>
      <p>
        Count:
        4
      </p>
      ...

     25|     expect(screen.getByText("Count: 2")).toBeInTheDocument();
       |                   ^

 Test Files  1 failed (1)
      Tests  1 failed | 2 passed (3)

(I trimmed the message a little.) Look at how useful this is. It tells you which test failed, the exact line, and it prints what is actually on the page. We clicked twice, and the page says Count: 4, so the bug is visible right away. I put the code back after that.

Testing Forms

Forms are where tests really earn their keep, because there is a lot of behavior to check. Here is a todo list that builds on the ideas from forms in React (https://www.kirupa.com/react/forms_in_react.htm). You can add tasks, and each one has a remove button:

import { useState } from "react";

function TodoList() {
  const [items, setItems] = useState([]);
  const [text, setText] = useState("");

  function handleSubmit(e) {
    e.preventDefault();
    const trimmed = text.trim();
    if (trimmed === "") {
      return;
    }
    setItems([...items, { id: crypto.randomUUID(), text: trimmed }]);
    setText("");
  }

  function removeItem(id) {
    setItems(items.filter((item) => item.id !== id));
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="new-todo">New task</label>
      <input
        id="new-todo"
        value={text}
        onChange={(e) => setText(e.target.value)}
      />
      <button type="submit">Add</button>

      {items.length === 0 ? (
        <p>Nothing to do. Suspicious.</p>
      ) : (
        <ul>
          {items.map((item) => (
            <li key={item.id}>
              {item.text}
              <button type="button" onClick={() => removeItem(item.id)}>
                Remove {item.text}
              </button>
            </li>
          ))}
        </ul>
      )}
    </form>
  );
}

export default TodoList;

And here are tests for it. We check the empty state, adding a task, pressing Enter, ignoring blank input, and removing a task:

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, test } from "vitest";
import TodoList from "./TodoList";

describe("TodoList", () => {
  test("shows a message when there are no tasks", () => {
    render(<TodoList />);

    expect(screen.getByText("Nothing to do. Suspicious.")).toBeInTheDocument();
    expect(screen.queryByRole("list")).not.toBeInTheDocument();
  });

  test("adds a task and clears the input", async () => {
    const user = userEvent.setup();
    render(<TodoList />);

    await user.type(screen.getByLabelText("New task"), "Feed the cat");
    await user.click(screen.getByRole("button", { name: "Add" }));

    expect(screen.getByRole("listitem")).toHaveTextContent("Feed the cat");
    expect(screen.getByLabelText("New task")).toHaveValue("");
  });

  test("adds a task when Enter is pressed", async () => {
    const user = userEvent.setup();
    render(<TodoList />);

    await user.type(screen.getByLabelText("New task"), "Write tests{Enter}");

    expect(screen.getAllByRole("listitem")).toHaveLength(1);
  });

  test("ignores empty tasks", async () => {
    const user = userEvent.setup();
    render(<TodoList />);

    await user.type(screen.getByLabelText("New task"), "   ");
    await user.click(screen.getByRole("button", { name: "Add" }));

    expect(screen.queryByRole("listitem")).not.toBeInTheDocument();
  });

  test("removes a task", async () => {
    const user = userEvent.setup();
    render(<TodoList />);

    const input = screen.getByLabelText("New task");
    await user.type(input, "One{Enter}");
    await user.type(input, "Two{Enter}");
    expect(screen.getAllByRole("listitem")).toHaveLength(2);

    await user.click(screen.getByRole("button", { name: "Remove One" }));

    const items = screen.getAllByRole("listitem");
    expect(items).toHaveLength(1);
    expect(items[0]).toHaveTextContent("Two");
  });
});

There are some new tricks in there:

- getByLabelText("New task") finds the input through its <label>, exactly the way a person would. It is also a quiet check that your label is hooked up properly.
- user.type types into the input, one character at a time. Special keys go in curly braces, so "Write tests{Enter}" types the text and then presses Enter, which submits the form.
- queryByRole is the one to use when you expect something not to be there. The get versions throw an error if they find nothing, while query returns null, which is what you want to say .not.toBeInTheDocument() about.
- getAllByRole returns an array when there are several matches, like the list items.

One thing you won't find in these tests is the state. We never check that items has two things in it. We check what is on the screen, which is all a user can see.

Testing Callback Props

Components often tell their parent that something happened by calling a function they were given as a prop (see communicating with props (https://www.kirupa.com/react/communicating_with_props.htm)). To test that, we hand in a fake function and check whether it was called. Vitest calls that a mock, and creates one with vi.fn(). Here is a small subscribe form with a button that stays disabled until someone enters an email:

import { useState } from "react";

function SubscribeForm({ onSubscribe }) {
  const [email, setEmail] = useState("");

  function handleSubmit(e) {
    e.preventDefault();
    onSubscribe(email);
    setEmail("");
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
      />
      <button type="submit" disabled={email === ""}>
        Subscribe
      </button>
    </form>
  );
}

export default SubscribeForm;

And the tests:

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { expect, test, vi } from "vitest";
import SubscribeForm from "./SubscribeForm";

test("keeps the button disabled until there is an email", async () => {
  const user = userEvent.setup();
  render(<SubscribeForm onSubscribe={vi.fn()} />);

  const button = screen.getByRole("button", { name: "Subscribe" });
  expect(button).toBeDisabled();

  await user.type(screen.getByLabelText("Email"), "bruce@wayne.com");
  expect(button).toBeEnabled();
});

test("hands the email to onSubscribe", async () => {
  const user = userEvent.setup();
  const onSubscribe = vi.fn();
  render(<SubscribeForm onSubscribe={onSubscribe} />);

  await user.type(screen.getByLabelText("Email"), "bruce@wayne.com");
  await user.click(screen.getByRole("button", { name: "Subscribe" }));

  expect(onSubscribe).toHaveBeenCalledTimes(1);
  expect(onSubscribe).toHaveBeenCalledWith("bruce@wayne.com");
});

The vi.fn() function remembers every time it was called and what it was called with. Our test never needs a real parent component. It passes in the mock and then asks it questions with toHaveBeenCalledTimes and toHaveBeenCalledWith. Also, notice the first test: we grab the button once, and it is still the right element after the typing, since React updates the same element in place.

Testing Async Components

Here's the tricky one. When a component loads data (like in working with external data (https://www.kirupa.com/react/working_with_external_data.htm)), the content doesn't appear right away. It shows a loading message first, and the real content shows up later. There is also a second problem: you don't want your tests making real network requests. They would be slow, they would break when your internet does, and the data could change.

Here is a component that loads a list of heroes with fetch inside an effect (see effects with useEffect (https://www.kirupa.com/react/effects_with_useeffect.htm)):

import { useEffect, useState } from "react";

function HeroList() {
  const [heroes, setHeroes] = useState([]);
  const [status, setStatus] = useState("loading");

  useEffect(() => {
    let ignore = false;

    async function loadHeroes() {
      try {
        const response = await fetch("https://example.com/api/heroes");
        if (!response.ok) {
          throw new Error(`Request failed: ${response.status}`);
        }
        const data = await response.json();
        if (!ignore) {
          setHeroes(data);
          setStatus("done");
        }
      } catch {
        if (!ignore) {
          setStatus("error");
        }
      }
    }

    loadHeroes();
    return () => {
      ignore = true;
    };
  }, []);

  if (status === "loading") {
    return <p>Loading heroes...</p>;
  }

  if (status === "error") {
    return <p role="alert">Could not load the heroes.</p>;
  }

  return (
    <ul>
      {heroes.map((hero) => (
        <li key={hero.id}>{hero.name}</li>
      ))}
    </ul>
  );
}

export default HeroList;

To test it, we replace fetch with a fake that answers instantly with whatever we want. Vitest's vi.spyOn does this, and we undo it after each test so it doesn't leak into the others:

import { render, screen } from "@testing-library/react";
import { afterEach, describe, expect, test, vi } from "vitest";
import HeroList from "./HeroList";

describe("HeroList", () => {
  afterEach(() => {
    vi.restoreAllMocks();
  });

  test("shows the heroes once they load", async () => {
    vi.spyOn(globalThis, "fetch").mockResolvedValue(
      Response.json([
        { id: 1, name: "Batman" },
        { id: 2, name: "Sherlock Holmes" },
      ]),
    );

    render(<HeroList />);
    expect(screen.getByText("Loading heroes...")).toBeInTheDocument();

    const items = await screen.findAllByRole("listitem");
    expect(items).toHaveLength(2);
    expect(items[0]).toHaveTextContent("Batman");
    expect(screen.queryByText("Loading heroes...")).not.toBeInTheDocument();
  });

  test("shows an error when the request fails", async () => {
    vi.spyOn(globalThis, "fetch").mockResolvedValue(
      new Response("Nope", { status: 500 }),
    );

    render(<HeroList />);

    expect(await screen.findByRole("alert")).toHaveTextContent(
      "Could not load the heroes.",
    );
  });
});

The important part is findAllByRole and findByRole. Queries that start with find are asynchronous: they wait, checking over and over (for up to a second by default) for the element to show up. That is exactly what you want when something appears a moment after the component renders. The tests above also check the loading state first (getByText works there since it is on the screen immediately) and then wait for the real thing.

The Response.json(...) and new Response(...) bits are the built-in Response object that comes with modern Node, so no extra libraries are needed to make a believable reply. The second test returns a 500 status, which proves that our error path works, something that is a pain to check by hand since you'd have to break a server on purpose.

For bigger apps, many teams use a library called Mock Service Worker (MSW) to fake an entire API instead of mocking fetch directly. It is a great option, but it is more setup than we need for this tutorial, so I'm leaving it for you to explore later.

Finding Things: Queries and Roles

You've now used a handful of different queries, so let's sort out how they fit together. The name of every query has two parts. The first part says what happens when it doesn't find anything:

- getBy...: Returns the element, and throws an error if it isn't there. Use this when you expect it to exist right now.
- queryBy...: Returns the element, or null if it isn't there. Use this to check that something is absent.
- findBy...: Returns a promise and waits for the element to show up. Use this for anything async.

Each of these also has an All version (getAllBy...) for when you expect more than one match. The second part says how it looks for the element: ByRole, ByLabelText, ByText, ByPlaceholderText, and so on.

So which one to pick? The Testing Library docs have a priority order, and the short version is to reach for ByRole first. Roles are how assistive technology (like a screen reader) understands the page: a <button> has the role button, a <ul> is a list, an <li> is a listitem, and the role="alert" we added is an alert. When you find elements that way, you are testing the page the same way a person using a screen reader would experience it. If a test can't find your button by role and name, there's a decent chance that a real user can't either. After ByRole, use ByLabelText for form fields, then ByText for plain content. There is also ByTestId, which looks for a data-testid attribute you add yourself. It works, but save it for the rare case where nothing else can find the element.

What happens when a query can't find what you asked for? That is actually one of the best parts of the library. Here is what I got when I deliberately misspelled a button's name as "Incremant":

TestingLibraryElementError: Unable to find an accessible element with the role "button" and name "Incremant"

Here are the accessible roles:

  paragraph:

  Name "":
  <p />

  --------------------------------------------------
  button:

  Name "Decrement":
  <button />

  Name "Increment":
  <button />

It lists every role on the page, along with the names of the things in each one, so the typo is obvious: the buttons are called Decrement and Increment. (I trimmed the end of this one.) If you are ever stuck on why a query isn't working, screen.debug() prints the current page to the terminal, and it is a fine way to see what your component rendered.

Things to Keep in Mind

- Test behavior, not implementation. Ask what the user can do and see. Don't check state variables, internal function names, or how many times something rendered.
- You don't need to test everything. Aim for the things that matter or that tend to break: logic with branches, forms, anything with an error state. A test for a component that only renders a heading doesn't buy you much.
- Keep each test independent. Every test should set up its own component with render and shouldn't depend on one that ran before it.
- jsdom is not a real browser. It doesn't do layout, so it can't tell you whether something looks right or is visible by size and position. Things like that need a browser-based tool such as Playwright or Cypress, which test a full running app, and which are a different kind of test from the ones you wrote here.
- Custom hooks can be tested too. React Testing Library has a renderHook function for that, which is handy for a hook from building custom hooks (https://www.kirupa.com/react/custom_hooks.htm). Often, though, testing a component that uses the hook is the more honest test.
- Coverage is available but optional. If you want a report of which lines your tests ran, Vitest supports it through an extra package (@vitest/coverage-v8). Treat the number as a hint rather than a goal.

Conclusion

You now have a complete testing setup, and you've seen it handle the kinds of things real components do. Vitest runs the tests, jsdom gives them a page to work with, React Testing Library renders your components and finds things by role and label, and user-event clicks and types for you. We tested rendering, button clicks, forms, callback props, and data loading, and we watched a test fail for the right reason.

The habit I'd encourage is to write a test whenever you fix a bug. Reproduce the bug in a test, watch it fail, fix the code, and watch it pass. That way, the same bug can never sneak back in without you knowing about it.

Happy testing!