Testing React Components

Q: How do I test that an element is NOT rendered (conditional rendering)?

Use queryBy which returns null instead of throwing:

Q: How do I test a specific item in a list?

Use within() to scope queries to a container:

Q: How do I test that a component updates when props change?

Use rerender from the render result:

Q: Gotcha: Why does screen.getByText("Delete") match the wrong button?

If multiple elements contain the same text, getByText matches the first one. Use within() to scope to a specific parent, or use unique aria-label attributes.

Q: Gotcha: What happens if I forget to await userEvent methods?

In userEvent v14+, all methods are async. Without await, interactions may not complete before assertions run, causing false positives or flaky tests.

Q: What is the difference between inline snapshots and regular snapshots?

Regular snapshots save output to a separate .snap file. Inline snapshots embed the expected value directly in the test file, making them easier to review for small output.

Test component rendering, user interactions, conditional UI, and dynamic content with confidence.

Recipe

Quick-reference recipe card -- copy-paste ready.

import { render, screen, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
 
// Test rendering with props
render(<Alert severity="warning" message="Disk full" />);
expect(screen.getByRole("alert")).toHaveTextContent("Disk full");
 
// Test user interactions
const user = userEvent.setup();
await user.click(screen.getByRole("button", { name: /delete/i }));
expect(screen.queryByText("Item 1")).not.toBeInTheDocument();
 
// Test conditional rendering
render(<Banner show={false} />);
expect(screen.queryByRole("banner")).not.toBeInTheDocument();
 
// Test lists
const items = screen.getAllByRole("listitem");
expect(items).toHaveLength(3);
expect(within(items[0]).getByText("First")).toBeInTheDocument();

When to reach for this: Whenever you build a component that renders props, handles interactions, or shows conditional UI.

Working Example

// src/components/todo-list.tsx
"use client";
 
import { useState } from "react";
 
interface Todo {
  id: string;
  text: string;
  completed: boolean;
}
 
export function TodoList({ initialTodos = [] }: { initialTodos?: Todo[] }) {
  const [todos, setTodos] = useState<Todo[]>(initialTodos);
  const [input, setInput] = useState("");
 
  function addTodo() {
    if (!input.trim()) return;
    setTodos((prev) => [
      ...prev,
      { id: crypto.randomUUID(), text: input.trim(), completed: false },
    ]);
    setInput("");
  }
 
  function toggleTodo(id: string) {
    setTodos((prev) =>
      prev.map((t) => (t.id === id ? { ...t, completed: !t.completed } : t))
    );
  }
 
  function deleteTodo(id: string) {
    setTodos((prev) => prev.filter((t) => t.id !== id));
  }
 
  const remaining = todos.filter((t) => !t.completed).length;
 
  return (
    <section aria-label="Todo list">
      <form
        onSubmit={(e) => {
          e.preventDefault();
          addTodo();
        }}
      >
        <label htmlFor="new-todo">New todo</label>
        <input
          id="new-todo"
          value={input}
          onChange={(e) => setInput(e.target.value)}
        />
        <button type="submit">Add</button>
      </form>
 
      {todos.length === 0 ? (
        <p>No todos yet. Add one above!</p>
      ) : (
        <>
          <ul>
            {todos.map((todo) => (
              <li key={todo.id}>
                <label>
                  <input
                    type="checkbox"
                    checked={todo.completed}
                    onChange={() => toggleTodo(todo.id)}
                  />
                  <span
                    style={{
                      textDecoration: todo.completed ? "line-through" : "none",
                    }}
                  >
                    {todo.text}
                  </span>
                </label>
                <button
                  onClick={() => deleteTodo(todo.id)}
                  aria-label={`Delete ${todo.text}`}
                >
                  Delete
                </button>
              </li>
            ))}
          </ul>
          <p>{remaining} item{remaining !== 1 ? "s" : ""} remaining</p>
        </>
      )}
    </section>
  );
}

// src/components/todo-list.test.tsx
import { render, screen, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { vi, describe, it, expect, beforeEach } from "vitest";
import { TodoList } from "./todo-list";
 
// Mock crypto.randomUUID for deterministic IDs
beforeEach(() => {
  let counter = 0;
  vi.stubGlobal("crypto", {
    randomUUID: () => `test-id-${++counter}`,
  });
});
 
describe("TodoList", () => {
  const user = userEvent.setup();
 
  describe("empty state", () => {
    it("shows empty message when no todos", () => {
      render(<TodoList />);
      expect(screen.getByText(/no todos yet/i)).toBeInTheDocument();
    });
 
    it("does not show the list", () => {
      render(<TodoList />);
      expect(screen.queryByRole("list")).not.toBeInTheDocument();
    });
  });
 
  describe("rendering with initial todos", () => {
    const todos = [
      { id: "1", text: "Write tests", completed: false },
      { id: "2", text: "Fix bugs", completed: true },
    ];
 
    it("renders all todos", () => {
      render(<TodoList initialTodos={todos} />);
      expect(screen.getAllByRole("listitem")).toHaveLength(2);
      expect(screen.getByText("Write tests")).toBeInTheDocument();
      expect(screen.getByText("Fix bugs")).toBeInTheDocument();
    });
 
    it("shows completed todos with checked checkbox", () => {
      render(<TodoList initialTodos={todos} />);
      const items = screen.getAllByRole("listitem");
      const fixBugsItem = items[1];
      expect(within(fixBugsItem).getByRole("checkbox")).toBeChecked();
    });
 
    it("shows remaining count", () => {
      render(<TodoList initialTodos={todos} />);
      expect(screen.getByText("1 item remaining")).toBeInTheDocument();
    });
  });
 
  describe("adding todos", () => {
    it("adds a new todo on form submit", async () => {
      render(<TodoList />);
      await user.type(screen.getByLabelText(/new todo/i), "Buy milk");
      await user.click(screen.getByRole("button", { name: /add/i }));
 
      expect(screen.getByText("Buy milk")).toBeInTheDocument();
      expect(screen.getByLabelText(/new todo/i)).toHaveValue("");
    });
 
    it("does not add empty todos", async () => {
      render(<TodoList />);
      await user.click(screen.getByRole("button", { name: /add/i }));
      expect(screen.queryByRole("list")).not.toBeInTheDocument();
    });
  });
 
  describe("toggling todos", () => {
    it("toggles completion on checkbox click", async () => {
      render(
        <TodoList
          initialTodos={[{ id: "1", text: "Test", completed: false }]}
        />
      );
      const checkbox = screen.getByRole("checkbox");
      expect(checkbox).not.toBeChecked();
 
      await user.click(checkbox);
      expect(checkbox).toBeChecked();
      expect(screen.getByText("0 items remaining")).toBeInTheDocument();
    });
  });
 
  describe("deleting todos", () => {
    it("removes todo on delete click", async () => {
      render(
        <TodoList
          initialTodos={[{ id: "1", text: "Test", completed: false }]}
        />
      );
      await user.click(screen.getByRole("button", { name: /delete test/i }));
 
      expect(screen.queryByText("Test")).not.toBeInTheDocument();
      expect(screen.getByText(/no todos yet/i)).toBeInTheDocument();
    });
  });
});

What this demonstrates:

Testing empty state, initial rendering, and dynamic updates
User interactions: typing, clicking, form submission
Conditional rendering assertions with queryBy
Scoped queries with within()
Accessible aria-label for targeted delete button queries

Deep Dive

How It Works

Each render() call creates a fresh DOM tree -- tests are isolated by default
within() scopes queries to a specific container element, useful for testing individual list items
queryBy returns null instead of throwing, making it ideal for asserting absence
getAllBy returns an array of matching elements -- use .toHaveLength() to assert list sizes
Testing Library auto-cleans up after each test (unmounts and removes DOM nodes)

Variations

Snapshot testing (use sparingly):

it("matches snapshot", () => {
  const { container } = render(
    <Alert severity="error" message="Something broke" />
  );
  expect(container.firstChild).toMatchSnapshot();
});
// Snapshots are useful for detecting unintended UI changes
// but are brittle and often auto-updated without review

Inline snapshots for small output:

it("renders correct class names", () => {
  render(<Badge variant="success">OK</Badge>);
  expect(screen.getByText("OK").className).toMatchInlineSnapshot(
    `"badge badge-success"`
  );
});

Testing with rerender for prop changes:

it("updates when severity changes", () => {
  const { rerender } = render(<Alert severity="info" message="Note" />);
  expect(screen.getByRole("alert")).toHaveClass("alert-info");
 
  rerender(<Alert severity="error" message="Note" />);
  expect(screen.getByRole("alert")).toHaveClass("alert-error");
});

TypeScript Notes

// Type-safe test factories for complex props
function createTodo(overrides: Partial<Todo> = {}): Todo {
  return {
    id: crypto.randomUUID(),
    text: "Default todo",
    completed: false,
    ...overrides,
  };
}
 
// Use in tests
render(<TodoList initialTodos={[createTodo({ text: "Custom" })]} />);

Gotchas

Testing implementation details -- Checking internal state, instance methods, or CSS class names ties tests to code structure. Fix: Assert what the user sees -- text content, visibility, enabled/disabled state.
Over-relying on snapshots -- Large snapshots are hard to review and get rubber-stamped on update. Fix: Use snapshots only for small, stable output. Prefer explicit assertions.
Forgetting to await userEvent -- All userEvent methods return promises in v14+. Fix: Always await them or the test may pass before the interaction completes.
Not using within() for list items -- screen.getByText("Delete") matches the first delete button on the page. Fix: Scope to the specific list item with within() or use unique aria-label attributes.
Testing too many things in one test -- Tests that add, toggle, and delete in a single it block are hard to debug when they fail. Fix: Write focused tests for each behavior.

Alternatives

Alternative	Use When	Don't Use When
Storybook + Chromatic	You need visual regression testing alongside component stories	You only need behavioral tests
Playwright Component Testing	You need real browser rendering (canvas, complex CSS)	Fast unit-level component tests are sufficient
Snapshot testing only	Guarding against unintended changes in stable, small components	Components change frequently or snapshots are large

FAQs

How do I test that an element is NOT rendered (conditional rendering)?

Use queryBy which returns null instead of throwing:

render(<Banner show={false} />);
expect(screen.queryByRole("banner")).not.toBeInTheDocument();

How do I test a specific item in a list?

Use within() to scope queries to a container:

const items = screen.getAllByRole("listitem");
expect(within(items[0]).getByText("First")).toBeInTheDocument();

When should I use snapshot testing?

Use sparingly, only for small and stable output.
Snapshots are brittle and often auto-updated without proper review.
Prefer explicit assertions like toHaveTextContent or toBeInTheDocument.

How do I test that a component updates when props change?

Use rerender from the render result:

const { rerender } = render(<Alert severity="info" message="Note" />);
rerender(<Alert severity="error" message="Note" />);
expect(screen.getByRole("alert")).toHaveClass("alert-error");

Gotcha: Why does `screen.getByText("Delete")` match the wrong button?

If multiple elements contain the same text, getByText matches the first one. Use within() to scope to a specific parent, or use unique aria-label attributes.

How do I mock `crypto.randomUUID()` for deterministic test IDs?

let counter = 0;
vi.stubGlobal("crypto", {
  randomUUID: () => `test-id-${++counter}`,
});

Why should I write focused tests instead of testing multiple behaviors in one `it` block?

Focused tests are easier to debug when they fail.
The test name tells you exactly what broke.
Multi-behavior tests give vague failure messages.

Gotcha: What happens if I forget to `await` userEvent methods?

In userEvent v14+, all methods are async. Without await, interactions may not complete before assertions run, causing false positives or flaky tests.

How do I create a type-safe test factory for complex props in TypeScript?

function createTodo(overrides: Partial<Todo> = {}): Todo {
  return {
    id: crypto.randomUUID(),
    text: "Default todo",
    completed: false,
    ...overrides,
  };
}

Does Testing Library automatically clean up after each test?

Yes. Modern Testing Library auto-cleans up after each test by unmounting components and removing DOM nodes. You do not need to call cleanup() manually.

How do I assert the number of items in a list?

const items = screen.getAllByRole("listitem");
expect(items).toHaveLength(3);

What is the difference between inline snapshots and regular snapshots?

Regular snapshots save output to a separate .snap file.
Inline snapshots embed the expected value directly in the test file, making them easier to review for small output.

React Testing Library Fundamentals -- query and assertion basics
Testing Custom Hooks -- testing hooks outside components
Testing Forms -- form-specific testing patterns
Testing Async Behavior -- loading and error states

Recipe

Quick-reference recipe card -- copy-paste ready.

import { render, screen, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
 
// Test rendering with props
render(<Alert severity="warning" message="Disk full" />);
expect(screen.getByRole("alert")).toHaveTextContent("Disk full");
 
// Test user interactions
const user = userEvent.setup();
await user.click(screen.getByRole("button", { name: /delete/i }));
expect(screen.queryByText("Item 1")).not.toBeInTheDocument();
 
// Test conditional rendering
render(<Banner show={false} />);
expect(screen.queryByRole("banner")).not.toBeInTheDocument();
 
// Test lists
const items = screen.getAllByRole("listitem");
expect(items).toHaveLength(3);
expect(within(items[0]).getByText("First")).toBeInTheDocument();

When to reach for this: Whenever you build a component that renders props, handles interactions, or shows conditional UI.

Working Example

// src/components/todo-list.tsx
"use client";
 
import { useState } from "react";
 
interface Todo {
  id: string;
  text: string;
  completed: boolean;
}
 
export function TodoList({ initialTodos = [] }: { initialTodos?: Todo[] }) {
  const [todos, setTodos] = useState<Todo[]>(initialTodos);
  const [input, setInput] = useState("");
 
  function addTodo() {
    if (!input.trim()) return;
    setTodos((prev) => [
      ...prev,
      { id: crypto.randomUUID(), text: input.trim(), completed: false },
    ]);
    setInput("");
  }
 
  function toggleTodo(id: string) {
    setTodos((prev) =>
      prev.map((t) => (t.id === id ? { ...t, completed: !t.completed } : t))
    );
  }
 
  function deleteTodo(id: string) {
    setTodos((prev) => prev.filter((t) => t.id !== id));
  }
 
  const remaining = todos.filter((t) => !t.completed).length;
 
  return (
    <section aria-label="Todo list">
      <form
        onSubmit={(e) => {
          e.preventDefault();
          addTodo();
        }}
      >
        <label htmlFor="new-todo">New todo</label>
        <input
          id="new-todo"
          value={input}
          onChange={(e) => setInput(e.target.value)}
        />
        <button type="submit">Add</button>
      </form>
 
      {todos.length === 0 ? (
        <p>No todos yet. Add one above!</p>
      ) : (
        <>
          <ul>
            {todos.map((todo) => (
              <li key={todo.id}>
                <label>
                  <input
                    type="checkbox"
                    checked={todo.completed}
                    onChange={() => toggleTodo(todo.id)}
                  />
                  <span
                    style={{
                      textDecoration: todo.completed ? "line-through" : "none",
                    }}
                  >
                    {todo.text}
                  </span>
                </label>
                <button
                  onClick={() => deleteTodo(todo.id)}
                  aria-label={`Delete ${todo.text}`}
                >
                  Delete
                </button>
              </li>
            ))}
          </ul>
          <p>{remaining} item{remaining !== 1 ? "s" : ""} remaining</p>
        </>
      )}
    </section>
  );
}

// src/components/todo-list.test.tsx
import { render, screen, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { vi, describe, it, expect, beforeEach } from "vitest";
import { TodoList } from "./todo-list";
 
// Mock crypto.randomUUID for deterministic IDs
beforeEach(() => {
  let counter = 0;
  vi.stubGlobal("crypto", {
    randomUUID: () => `test-id-${++counter}`,
  });
});
 
describe("TodoList", () => {
  const user = userEvent.setup();
 
  describe("empty state", () => {
    it("shows empty message when no todos", () => {
      render(<TodoList />);
      expect(screen.getByText(/no todos yet/i)).toBeInTheDocument();
    });
 
    it("does not show the list", () => {
      render(<TodoList />);
      expect(screen.queryByRole("list")).not.toBeInTheDocument();
    });
  });
 
  describe("rendering with initial todos", () => {
    const todos = [
      { id: "1", text: "Write tests", completed: false },
      { id: "2", text: "Fix bugs", completed: true },
    ];
 
    it("renders all todos", () => {
      render(<TodoList initialTodos={todos} />);
      expect(screen.getAllByRole("listitem")).toHaveLength(2);
      expect(screen.getByText("Write tests")).toBeInTheDocument();
      expect(screen.getByText("Fix bugs")).toBeInTheDocument();
    });
 
    it("shows completed todos with checked checkbox", () => {
      render(<TodoList initialTodos={todos} />);
      const items = screen.getAllByRole("listitem");
      const fixBugsItem = items[1];
      expect(within(fixBugsItem).getByRole("checkbox")).toBeChecked();
    });
 
    it("shows remaining count", () => {
      render(<TodoList initialTodos={todos} />);
      expect(screen.getByText("1 item remaining")).toBeInTheDocument();
    });
  });
 
  describe("adding todos", () => {
    it("adds a new todo on form submit", async () => {
      render(<TodoList />);
      await user.type(screen.getByLabelText(/new todo/i), "Buy milk");
      await user.click(screen.getByRole("button", { name: /add/i }));
 
      expect(screen.getByText("Buy milk")).toBeInTheDocument();
      expect(screen.getByLabelText(/new todo/i)).toHaveValue("");
    });
 
    it("does not add empty todos", async () => {
      render(<TodoList />);
      await user.click(screen.getByRole("button", { name: /add/i }));
      expect(screen.queryByRole("list")).not.toBeInTheDocument();
    });
  });
 
  describe("toggling todos", () => {
    it("toggles completion on checkbox click", async () => {
      render(
        <TodoList
          initialTodos={[{ id: "1", text: "Test", completed: false }]}
        />
      );
      const checkbox = screen.getByRole("checkbox");
      expect(checkbox).not.toBeChecked();
 
      await user.click(checkbox);
      expect(checkbox).toBeChecked();
      expect(screen.getByText("0 items remaining")).toBeInTheDocument();
    });
  });
 
  describe("deleting todos", () => {
    it("removes todo on delete click", async () => {
      render(
        <TodoList
          initialTodos={[{ id: "1", text: "Test", completed: false }]}
        />
      );
      await user.click(screen.getByRole("button", { name: /delete test/i }));
 
      expect(screen.queryByText("Test")).not.toBeInTheDocument();
      expect(screen.getByText(/no todos yet/i)).toBeInTheDocument();
    });
  });
});

What this demonstrates:

Testing empty state, initial rendering, and dynamic updates
User interactions: typing, clicking, form submission
Conditional rendering assertions with queryBy
Scoped queries with within()
Accessible aria-label for targeted delete button queries

Deep Dive

How It Works

Each render() call creates a fresh DOM tree -- tests are isolated by default
within() scopes queries to a specific container element, useful for testing individual list items
queryBy returns null instead of throwing, making it ideal for asserting absence
getAllBy returns an array of matching elements -- use .toHaveLength() to assert list sizes
Testing Library auto-cleans up after each test (unmounts and removes DOM nodes)

Variations

Snapshot testing (use sparingly):

it("matches snapshot", () => {
  const { container } = render(
    <Alert severity="error" message="Something broke" />
  );
  expect(container.firstChild).toMatchSnapshot();
});
// Snapshots are useful for detecting unintended UI changes
// but are brittle and often auto-updated without review

Inline snapshots for small output:

it("renders correct class names", () => {
  render(<Badge variant="success">OK</Badge>);
  expect(screen.getByText("OK").className).toMatchInlineSnapshot(
    `"badge badge-success"`
  );
});

Testing with rerender for prop changes:

it("updates when severity changes", () => {
  const { rerender } = render(<Alert severity="info" message="Note" />);
  expect(screen.getByRole("alert")).toHaveClass("alert-info");
 
  rerender(<Alert severity="error" message="Note" />);
  expect(screen.getByRole("alert")).toHaveClass("alert-error");
});

TypeScript Notes

// Type-safe test factories for complex props
function createTodo(overrides: Partial<Todo> = {}): Todo {
  return {
    id: crypto.randomUUID(),
    text: "Default todo",
    completed: false,
    ...overrides,
  };
}
 
// Use in tests
render(<TodoList initialTodos={[createTodo({ text: "Custom" })]} />);

Gotchas

Testing implementation details -- Checking internal state, instance methods, or CSS class names ties tests to code structure. Fix: Assert what the user sees -- text content, visibility, enabled/disabled state.
Over-relying on snapshots -- Large snapshots are hard to review and get rubber-stamped on update. Fix: Use snapshots only for small, stable output. Prefer explicit assertions.
Forgetting to await userEvent -- All userEvent methods return promises in v14+. Fix: Always await them or the test may pass before the interaction completes.
Not using within() for list items -- screen.getByText("Delete") matches the first delete button on the page. Fix: Scope to the specific list item with within() or use unique aria-label attributes.
Testing too many things in one test -- Tests that add, toggle, and delete in a single it block are hard to debug when they fail. Fix: Write focused tests for each behavior.

Alternatives

Alternative	Use When	Don't Use When
Storybook + Chromatic	You need visual regression testing alongside component stories	You only need behavioral tests
Playwright Component Testing	You need real browser rendering (canvas, complex CSS)	Fast unit-level component tests are sufficient
Snapshot testing only	Guarding against unintended changes in stable, small components	Components change frequently or snapshots are large

FAQs

How do I test that an element is NOT rendered (conditional rendering)?

Use queryBy which returns null instead of throwing:

render(<Banner show={false} />);
expect(screen.queryByRole("banner")).not.toBeInTheDocument();

How do I test a specific item in a list?

Use within() to scope queries to a container:

const items = screen.getAllByRole("listitem");
expect(within(items[0]).getByText("First")).toBeInTheDocument();

When should I use snapshot testing?

Use sparingly, only for small and stable output.
Snapshots are brittle and often auto-updated without proper review.
Prefer explicit assertions like toHaveTextContent or toBeInTheDocument.

How do I test that a component updates when props change?

Use rerender from the render result:

const { rerender } = render(<Alert severity="info" message="Note" />);
rerender(<Alert severity="error" message="Note" />);
expect(screen.getByRole("alert")).toHaveClass("alert-error");

Gotcha: Why does `screen.getByText("Delete")` match the wrong button?

If multiple elements contain the same text, getByText matches the first one. Use within() to scope to a specific parent, or use unique aria-label attributes.

How do I mock `crypto.randomUUID()` for deterministic test IDs?

let counter = 0;
vi.stubGlobal("crypto", {
  randomUUID: () => `test-id-${++counter}`,
});

Why should I write focused tests instead of testing multiple behaviors in one `it` block?

Focused tests are easier to debug when they fail.
The test name tells you exactly what broke.
Multi-behavior tests give vague failure messages.

Gotcha: What happens if I forget to `await` userEvent methods?

In userEvent v14+, all methods are async. Without await, interactions may not complete before assertions run, causing false positives or flaky tests.

How do I create a type-safe test factory for complex props in TypeScript?

function createTodo(overrides: Partial<Todo> = {}): Todo {
  return {
    id: crypto.randomUUID(),
    text: "Default todo",
    completed: false,
    ...overrides,
  };
}

Does Testing Library automatically clean up after each test?

Yes. Modern Testing Library auto-cleans up after each test by unmounting components and removing DOM nodes. You do not need to call cleanup() manually.

How do I assert the number of items in a list?

const items = screen.getAllByRole("listitem");
expect(items).toHaveLength(3);

What is the difference between inline snapshots and regular snapshots?

Regular snapshots save output to a separate .snap file.
Inline snapshots embed the expected value directly in the test file, making them easier to review for small output.

React Testing Library Fundamentals -- query and assertion basics
Testing Custom Hooks -- testing hooks outside components
Testing Forms -- form-specific testing patterns
Testing Async Behavior -- loading and error states

Testing React Components

Search Documentation

Testing React Components