Testing React Components

Testing what users see and do, not implementation details - React Testing Library, queries, user-event, and mocking patterns.

What it is, in plain English: Testing React components means rendering them in a simulated DOM and asserting what a user would actually see and be able to do -- not checking internal state or implementation details. React Testing Library is the standard tool: it renders components, lets you query the result the way a user would find things (by visible text, label, or role), and simulates real user interactions like clicks and typing.

Testing what the user sees, not how it's built

React Testing Library's core philosophy: the more your tests resemble the way your software is used, the more confidence they give you. Instead of checking a component's internal state directly, you render it and interact with it the way a real user would -- finding buttons by their text, typing into inputs, clicking things.

Setup

// npm install -D @testing-library/react @testing-library/user-event vitest jsdom
// (jsdom simulates a browser DOM in Node.js, where tests actually run)

A basic test

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

function Greeting({ name }) {
  return <h1>Hello, {name}!</h1>;
}

test("renders the greeting with the given name", () => {
  render(<Greeting name="Alice" />);

  // screen.getByText finds an element by its visible text:
  expect(screen.getByText("Hello, Alice!")).toBeInTheDocument();
});

Simulating user interaction

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

function Counter() {
  const [count, setCount] = React.useState(0);
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

test("increments when clicked", async () => {
  const user = userEvent.setup();
  render(<Counter />);

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

  const button = screen.getByRole("button", { name: "Increment" });
  await user.click(button);   // simulates a REAL click — focus, mousedown, mouseup, click

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

Testing forms

test("submits the form with typed values", async () => {
  const user = userEvent.setup();
  render(<LoginForm />);

  const emailInput = screen.getByLabelText("Email");
  await user.type(emailInput, "alice@example.com");

  const submitButton = screen.getByRole("button", { name: "Log In" });
  await user.click(submitButton);

  expect(screen.getByText("Welcome, alice@example.com")).toBeInTheDocument();
});

Try It Yourself (JSX)

// React Testing Library -- testing what users see and do
// (Conceptual demo -- @testing-library/react needs a DOM test environment to run)

const TEST_EXAMPLE = `
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { test, expect } from "vitest";
import Counter from "./Counter";

test("increments the count when button is clicked", async () => {
  const user = userEvent.setup();
  render(<Counter />);

// Query by what the USER sees -- text content, not implementation:
  expect(screen.getByText("Count: 0")).toBeInTheDocument();

// Simulate a real click (not just firing an event programmatically):
  const button = screen.getByRole("button", { name: /increment/i });
  await user.click(button);

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

console.log("Component being tested:");
console.log(COUNTER_COMPONENT.trim());
console.log("\nTest:");
console.log(TEST_EXAMPLE.trim());

console.log("\nKey philosophy: query by ROLE, LABEL, or TEXT --");
console.log("the same way a real user (or screen reader) finds things.");
console.log("NOT by CSS class, NOT by component internal state, NOT by test IDs (last resort).");

// Demonstrating the query priority order TRL recommends:
const QUERY_PRIORITY = [
  "getByRole       -- most accessible, matches what assistive tech sees",
  "getByLabelText  -- form fields, by their associated label",
  "getByText       -- non-interactive text content",
  "getByTestId     -- last resort, only when nothing else works",
];
console.log("\nQuery priority (best to worst):");
QUERY_PRIORITY.forEach(q => console.log("  " + q));

function App() {
  const [count, setCount] = React.useState(0);
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
    </div>
  );
}

Query priority, mocking fetch, and async assertions

The query priority order (most to least recommended)

// 1. getByRole — matches what screen readers/assistive tech perceive (BEST):
screen.getByRole("button", { name: "Submit" });
screen.getByRole("textbox", { name: "Email" });
screen.getByRole("heading", { name: "Welcome" });

// 2. getByLabelText — for form fields:
screen.getByLabelText("Password");

// 3. getByText — for non-interactive content:
screen.getByText("Order confirmed");

// 4. getByTestId — LAST RESORT, when nothing semantic is available:
screen.getByTestId("custom-widget");
// <div data-testid="custom-widget">

// Why this order? Tests using getByRole/getByLabelText catch accessibility
// bugs for free — if a screen reader user couldn't find the button, your
// test can't either.

Mocking fetch

import { vi, test, expect } from "vitest";
import { render, screen, waitFor } from "@testing-library/react";

test("displays user data after fetch", async () => {
  global.fetch = vi.fn().mockResolvedValue({
    ok: true,
    json: async () => ({ name: "Alice" }),
  });

  render(<UserProfile userId={1} />);

  expect(screen.getByText("Loading...")).toBeInTheDocument();

  // waitFor retries the assertion until it passes (or times out) --
  // needed because the fetch resolves asynchronously:
  await waitFor(() => {
    expect(screen.getByText("Alice")).toBeInTheDocument();
  });

  expect(fetch).toHaveBeenCalledWith("/api/users/1");
});

findBy* queries -- built-in async waiting

// findByText is shorthand for getByText wrapped in waitFor:
test("shows data after loading", async () => {
  render(<UserProfile userId={1} />);

  // Waits automatically for the element to appear (default timeout 1000ms):
  const name = await screen.findByText("Alice");
  expect(name).toBeInTheDocument();
});

// Use getBy* for things that should ALREADY be there (synchronous)
// Use findBy* for things that will appear AFTER an async operation
// Use queryBy* to assert something is NOT present (returns null instead of throwing):
expect(screen.queryByText("Error")).not.toBeInTheDocument();

Mock Service Worker and testing custom hooks

// MSW (Mock Service Worker) — intercepts actual network requests at the
// network level, more realistic than mocking fetch() directly:
// npm install -D msw

import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";

const server = setupServer(
  http.get("/api/users/:id", ({ params }) => {
    return HttpResponse.json({ id: params.id, name: "Alice" });
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test("fetches and displays user", async () => {
  render(<UserProfile userId="1" />);
  expect(await screen.findByText("Alice")).toBeInTheDocument();
});
// Your component's actual fetch() call is intercepted transparently --
// no need to mock fetch itself, works with any HTTP client (axios, etc.)

Testing custom hooks in isolation

import { renderHook, act } from "@testing-library/react";

function useCounter(initial = 0) {
  const [count, setCount] = React.useState(initial);
  return { count, increment: () => setCount(c => c + 1) };
}

test("useCounter increments", () => {
  const { result } = renderHook(() => useCounter(5));

  expect(result.current.count).toBe(5);

  act(() => {
    result.current.increment();
  });

  expect(result.current.count).toBe(6);
});
// act() ensures all state updates and effects are flushed before assertions run --
// without it, React may warn about updates happening outside its expected lifecycle.

Official Sources

The Codex links only to official documentation. No third-party tutorials.