@testing-library/react 16.x

Complete instructions

React Testing Library 16

Read the project's runner, environment and installed peer versions. React Testing Library 16 works with React 18 or 19 and needs DOM Testing Library 10. The fixture uses @testing-library/react 16.3.3, @testing-library/dom 10.4.2, @testing-library/user-event 14.6.7 and matching React/React DOM 19.2.8. These companion packages have different majors; their versions must not be inferred from the React Testing Library version.

Configure the actual environment

Use the application's existing Jest or Vitest runner. React Testing Library does not require Jest. Set a DOM environment such as jsdom and use the runner's compatible assertion library. A plain Node import does not create document.

For Vitest with globals disabled, register cleanup explicitly:

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

afterEach(cleanup);

When the existing runner already supplies automatic cleanup, preserve its single cleanup owner instead of stacking multiple independent setup systems. Custom matchers such as toBeInTheDocument need @testing-library/jest-dom configured for the selected runner; they are not supplied by React Testing Library itself.

Describe the user-visible contract

Prefer role with accessible name, then labels or text appropriate to the task. Use a test ID when the semantic surface cannot identify the intended element. Avoid querying generated classes, component instances or internal state.

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

test("saves the entered name", async () => {
  const user = userEvent.setup();
  render(<NameForm />);
  await user.type(screen.getByRole("textbox", { name: "Name" }), "Ada");
  await user.click(screen.getByRole("button", { name: "Save" }));
  expect((await screen.findByRole("status")).textContent).toBe("Saved Ada");
});

This is an application test pattern; NameForm belongs to the consumer application. The fixture supplies its own bounded component and mocked persistence function.

Use getBy for something already present, queryBy for absence and findBy when it will appear asynchronously. Scope repeated UI with within rather than choosing an arbitrary array position. Await user-event interactions; it models event sequences and interactability more closely than a single fireEvent call. Reserve fireEvent for the low-level interaction that the chosen test genuinely needs.

Synchronize and isolate

React Testing Library wraps its renderer operations in act. Prefer awaited user interactions and asynchronous queries before adding a manual act wrapper. A warning often indicates unfinished work or a test that stops before the behavior settles. Use waitFor for a condition, not an arbitrary sleep, and keep side effects outside its retried callback.

Create userEvent.setup inside each test. When using fake timers, pass the runner's timer-advancement function through advanceTimers and restore real timers after the test; setting delay: null can hide an incorrect timer integration.

Unmount components and verify cleanup when the behavior involves subscriptions or external resources. Mock at the application's actual boundary and exercise a failure path as well as success. Keep DOM globals local to the chosen test environment; layout, navigation and browser APIs require a real browser test.

The fixture runs three actual Vitest/jsdom tests: asynchronous save success, error presentation and effect cleanup on unmount. It does not establish browser layout, React Native behavior or framework-specific rendering.

Sources

• React Testing Library setup
• DOM query semantics
• user-event setup
• user-event options and timers
• React Testing Library API