React Testing Library Patterns

Quick Guide: Query through the accessibility tree (getByRole first, getByTestId last), drive interactions with userEvent rather than fireEvent, and reach for findBy* whenever the element arrives asynchronously. userEvent has been async and setup()-first since v14, so every call is awaited. The library renders and interacts; the assertion API, mock functions and fake timers come from whatever test runner is executing the file.

Detailed Resources:

examples/core.md — query hierarchy, choosing between role, label, text and test id
examples/user-events.md — typing, clicking, keyboard shortcuts, tab order, and the cases fireEvent still covers
examples/async-testing.md — findBy*, waitFor, waitForElementToBeRemoved
examples/custom-render.md — a render wrapped in the app's providers, with per-test initial state
examples/hooks.md — renderHook, rerender, unmount, wrappers, hooks that throw
examples/accessibility.md — keyboard navigation, ARIA attributes, live regions, focus trapping
examples/scoped-queries.md — within() for tables, cards, sections and modals
examples/configuration.md — fake timers, pointer-events checks, timeout overrides
reference.md — query and role tables, userEvent methods, keyboard syntax, matcher list, debug checklist

Which path applies

A component is the subject — render it and query the resulting DOM; examples/core.md and examples/user-events.md are the path.
A bare hook is the subject — no DOM to query, so renderHook exposes result.current; examples/hooks.md. Where the hook only makes sense inside its UI, test the component instead.
The subject needs providers — theme, auth, routing — wrap once in a custom render rather than per test; examples/custom-render.md.

<critical_requirements>

Before writing React Testing Library code

Reach for queries in accessibility order — getByRole, then getByLabelText, then getByText, and getByTestId only when nothing else reaches the element. A query that has to fall back is telling you the element is unreachable to assistive technology too.

Call userEvent.setup() before the first interaction and await every method. Since v14 the methods return promises, so an un-awaited call lets assertions run against a DOM that has not finished updating.

Use findBy* for anything that arrives asynchronously. It retries and reports the DOM it gave up on, where waitFor wrapped around getBy* reports only the last thrown error.

Query through screen rather than the object render returns. One import serves every query, and the destructured form drifts out of step as a test grows.

Assert on what the user can see or operate. Internal state, refs and instance fields change under a refactor that keeps the behaviour identical.

</critical_requirements>

Auto-detection: @testing-library/react, @testing-library/user-event, @testing-library/dom, render, screen, userEvent.setup, fireEvent, waitFor, waitForElementToBeRemoved, findByRole, getByRole, getByLabelText, queryByRole, renderHook, result.current, within, cleanup, prettyDOM, logRoles, logTestingPlaygroundURL, testIdAttribute, asyncUtilTimeout

Applies to:

Rendering a React component and asserting on what it puts in the DOM
Driving forms, keyboard navigation and pointer interaction through a simulated user
Testing loading, error and success states that resolve asynchronously
Testing a custom hook in isolation, and deciding when not to
Building a render that carries the app's providers
Asserting that interactive elements are reachable by role, label and keyboard

Handled elsewhere:

Test runner mechanics — the file's describe/it, the assertion API, mock functions, fake timers and the setup file are the runner's; this skill only names the seam where an option must be handed the runner's timer-advance function
Test doubles for the network — a component is unaware of its transport, so responses are arranged by whatever intercepts them
Journeys spanning navigations and real backends — browser-driven end-to-end coverage
Whether a rendered frame still looks right — pixel comparison against an approved image

Philosophy

The library's own guiding principle: the more a test resembles the way the software is used, the more confidence it gives. Three consequences follow.

Queries are an accessibility audit that happens to be a test. A component reachable by getByRole("button", { name: /submit/i }) is reachable by a screen reader for the same reason. When the only query that works is getByTestId, the test has just reported a defect in the UI rather than in itself.

Implementation details are whatever survives a refactor unchanged. State shape, hook internals, class names and DOM nesting are all free to move; rendered text, roles and accessible names are the contract.

The DOM is real. Components render into a real document, so integration bugs between a component and its children surface here rather than in production.

</philosophy>

Core patterns

Pattern 1: Query Priority Hierarchy

Pick the query by how a user would find the element, not by what is convenient in the markup.

screen.getByRole("button", { name: /sign in/i }); // interactive elements
screen.getByLabelText(/password/i); // form fields, incl. password inputs (no textbox role)
screen.getByText(/welcome back/i); // non-interactive content
screen.getByDisplayValue("draft title"); // a field by its current value
screen.getByAltText(/profile photo/i); // images
screen.getByTestId(`product-${generatedId}`); // last resort: genuinely generated content

Full code: examples/core.md

Pattern 2: userEvent Over fireEvent

fireEvent dispatches one DOM event. userEvent replays the sequence a real interaction produces — pointer, focus and keyboard events in order — which is where handler bugs actually live.

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

const user = userEvent.setup(); // before the first interaction
await user.type(screen.getByLabelText(/email/i), "user@example.com");
await user.click(screen.getByRole("button", { name: /create account/i }));

Reach for fireEvent only for events a user does not originate — resize, scroll, a synthetic event carrying properties you need to control.

Full code: examples/user-events.md

Pattern 3: Async Utilities

findBy* when the element appears; waitFor only when the thing you are waiting on is an assertion rather than an element; waitForElementToBeRemoved when it disappears.

expect(await screen.findByText(/results/i)).toBeInTheDocument();

await waitFor(() => {
  expect(handler).toHaveBeenCalledWith("react"); // one assertion, no side effects
});

await waitForElementToBeRemoved(() => screen.queryByRole("progressbar"));

waitFor polls until its callback stops throwing, so a second assertion inside it pays the full retry cost before the first failure is reported, and a side effect inside it runs on every poll.

Full code: examples/async-testing.md

Pattern 4: Testing Hooks with renderHook

renderHook mounts a hook without a component. result.current is re-read on every access, so hold the access rather than the value.

const { result, rerender, unmount } = renderHook(
  ({ key }) => useLocalStorage(key, "initial"),
  { initialProps: { key: "draft" } },
);

act(() => {
  result.current[1]("updated");
});
expect(result.current[0]).toBe("updated");

Prefer a component test where the hook is inseparable from its UI; renderHook earns its place for hooks you publish, or hooks with edge cases a component would obscure.

Full code: examples/hooks.md

Pattern 5: Custom Render with Providers

Wrap the app's providers once and re-export, so no test repeats the nesting.

function customRender(
  ui: ReactElement,
  options?: Omit<RenderOptions, "wrapper">,
) {
  return render(ui, { wrapper: AllProviders, ...options });
}

export * from "@testing-library/react";
export { customRender as render }; // shadow the default export

Widen the options type to accept per-test initial state — an auth state, a starting route — so a test states its precondition instead of arranging it.

Full code: examples/custom-render.md

Pattern 6: Asserting Accessible Behaviour

Beyond finding elements, the accessibility tree is where keyboard order, expanded/selected state and announcements are asserted.

await user.tab();
expect(screen.getByRole("combobox")).toHaveFocus();

await user.keyboard("{Enter}");
expect(screen.getByRole("button", { name: /section 1/i })).toHaveAttribute(
  "aria-expanded",
  "true",
);

expect(await screen.findByRole("alert")).toHaveTextContent(
  /email is required/i,
);

Full code: examples/accessibility.md

Pattern 7: Scoped Queries with within

within bounds a query to a container, which is what makes repeated structures testable at all.

const bobRow = screen.getAllByRole("row")[2];
await user.click(within(bobRow).getByRole("button", { name: /edit/i }));

const billing = screen.getByRole("region", { name: /billing address/i });
await user.type(
  within(billing).getByLabelText(/street address/i),
  "123 Billing St",
);

Full code: examples/scoped-queries.md

Pattern 8: userEvent Setup Options

Three options change behaviour rather than tune it, and all three are set at setup().

const user = userEvent.setup({
  advanceTimers: advanceTimersBy, // your runner's timer-advance fn; without it, fake timers hang
  delay: null, // skip the inter-event wait
  pointerEventsCheck: 0, // interact with an element whose CSS sets pointer-events: none
});

Full code: examples/configuration.md

</patterns>

<red_flags>

Red flags

Breaks at runtime:

A userEvent call without await — assertions run against the pre-interaction DOM, and the test passes or fails by timing
Fake timers installed without passing advanceTimers to setup() — userEvent's internal delay never resolves and the test hangs until the runner's timeout
Calling userEvent.click(...) directly instead of on a setup() session — the direct API is deprecated and carries none of the session's pointer or keyboard state
getBy* for an element that arrives asynchronously — throws immediately rather than waiting
A side effect inside a waitFor callback — the callback runs on every poll, so the effect fires repeatedly

Surprising behaviour:

container.querySelector(".btn-primary") returns null rather than throwing, so the failure surfaces one line later at the assertion instead of at the query — and it matches on the class names and nesting a refactor is free to change, which is the whole thing the query hierarchy exists to avoid
queryBy* returns null instead of throwing, which is what makes it right for absence assertions and wrong for everything else
findBy* defaults to a 1000ms timeout, and its third argument — not its second — is where that is raised
result.current is re-read each time it is touched, so a value captured into a local goes stale after the next act
render, fireEvent and userEvent already wrap in act; wrapping them again is noise that also hides genuine act warnings
Cleanup runs automatically wherever the framework adapter is registered, so a manual afterEach(cleanup) is redundant
Multiple assertions in one waitFor pay the full retry window before the first failure surfaces
An empty waitFor(() => {}) waits for the next poll tick and nothing else — a sleep wearing a matcher's clothes
A large DOM snapshot fails with noise rather than with a reason; keep snapshots for small, stable output such as an icon or a breadcrumb
screen.debug() truncates at 7000 characters, which is why a debugged form often appears to end mid-element

</red_flags>