Testing with React Testing Library

Test what a user can see and do, not component internals. The query priority, the difference between getBy, queryBy and findBy, and simulating input with user-event.

After this lesson you can

Pick the right query for an element, preferring roles and labels over test ids
Choose between getBy, queryBy, findBy and their All variants from what each does with zero or several matches
Write an interaction test with user-event and assert on the result the user sees

React Testing Library (RTL) renders a component into a real DOM (usually jsdom under Jest or Vitest) and gives you ways to find elements the way a user would — by their role, their label, their text. It deliberately gives you no access to state, props or component instances. A test that only touches what the user sees keeps passing when you refactor the implementation, and fails when the behaviour breaks.

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

test("adds a todo", async () => {
  const user = userEvent.setup();
  render(<TodoApp />);

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

  expect(screen.getByRole("listitem")).toHaveTextContent("Buy milk");
  expect(screen.queryByText("No todos yet")).not.toBeInTheDocument();
});

(toHaveTextContent and toBeInTheDocument come from @testing-library/jest-dom.)

Which query

Prefer the queries that match how people — including people using assistive technology — find things: getByRole (with name) first, then getByLabelText for form fields, then getByPlaceholderText, getByText, getByDisplayValue, getByAltText, getByTitle, and getByTestId only when nothing else identifies the element. A test that cannot find a button by its role and name is often pointing at a real accessibility problem. By default ByRole queries also skip elements hidden from the accessibility tree.

get, query, find — and All

Every query comes in variants that differ only in what they do with zero or several matches:

	0 matches	1 match	2+ matches
`getBy`	throws	element	throws
`queryBy`	`null`	element	throws
`findBy`	rejects after timeout	resolves	rejects after timeout
`getAllBy`	throws	array	array
`queryAllBy`	`[]`	array	array
`findAllBy`

Use getBy when the element must be there, queryBy only to assert that something is absent, and findBy when it will appear later (after a fetch or a timer). The model below runs four small tests against a page that has two "Download" buttons and loses its "Delete" button when the user confirms; each test either finishes or reports the error that failed it:

Four tests, and which of them passnode-22

1// An invoice row: a Delete button, and a Download button for each of2// its two attachments. Confirming the delete removes the Delete button.3function renderInvoice() {4  let nodes = [5    { role: "button", name: "Delete" },6    { role: "button", name: "Download" },7    { role: "button", name: "Download" },8  ];9  const matching = (role, name) => nodes.filter((n) => n.role === role && n.name === name);10  const describe = (role, name, count) => `${count} elements match ${role} "${name}"`;11  return {12    confirmDelete() {13      nodes = nodes.filter((n) => n.name !== "Delete");14    },15    screen: {16      getByRole(role, { name }) {17        const m = matching(role, name);18        if (m.length !== 1) throw new Error(describe(role, name, m.length));19        return m[0];20      },21      queryByRole(role, { name }) {22        const m = matching(role, name);23        if (m.length > 1) throw new Error(describe(role, name, m.length));24        return m.length === 1 ? m[0] : null;25      },26      getAllByRole(role, { name }) {27        const m = matching(role, name);28        if (m.length === 0) throw new Error(describe(role, name, 0));29        return m;30      },31    },32  };33}34 35function expectEqual(actual, wanted) {36  if (actual !== wanted) throw new Error(`expected ${wanted}, received ${actual}`);37}38 39const tests = {40  "Delete is gone, checked with getBy"({ screen, confirmDelete }) {41    confirmDelete();42    expectEqual(screen.getByRole("button", { name: "Delete" }), null);43  },44  "Delete is gone, checked with queryBy"({ screen, confirmDelete }) {45    confirmDelete();46    expectEqual(screen.queryByRole("button", { name: "Delete" }), null);47  },48  "one Download button, via queryBy"({ screen }) {49    expectEqual(screen.queryByRole("button", { name: "Download" }) !== null, true);50  },51  "every Download button, via getAllBy"({ screen }) {52    expectEqual(screen.getAllByRole("button", { name: "Download" }).length, 2);53  },54};55 56export function run() {57  const report = {};58  for (const [name, body] of Object.entries(tests)) {59    try {60      body(renderInvoice());   // a fresh render for every test61      report[name] = "PASS";62    } catch (err) {63      report[name] = `FAIL: ${err.message}`;64    }65  }66  return report;67}

What to look for

Waiting for things that happen later

findBy is getBy retried until it passes or the timeout (1000 ms by default) runs out; waitFor(() => …) does the same for any assertion. A getBy right after an async action fails because the element is not there yet:

getBy fails now, findBy waitsnode-22

1const wait = (ms) => new Promise((r) => setTimeout(r, ms));2const dom = [];3 4// The "component" shows a result 30 ms after it renders (a fake fetch).5function renderComponent() {6  setTimeout(() => dom.push({ role: "listitem", name: "Buy milk" }), 30);7}8 9function getByRole(role) {10  const m = dom.filter((n) => n.role === role);11  if (m.length !== 1) throw new Error(`Unable to find role "${role}"`);12  return m[0];13}14 15async function findByRole(role, { timeout = 1000, interval = 10 } = {}) {16  const start = Date.now();17  for (;;) {18    try {19      return getByRole(role);20    } catch (err) {21      if (Date.now() - start > timeout) throw err;22      await wait(interval);23    }24  }25}26 27export async function run() {28  renderComponent();29  let immediate;30  try {31    immediate = getByRole("listitem").name;32  } catch (err) {33    immediate = `throws: ${err.message}`;34  }35  const found = await findByRole("listitem");36  let missing;37  try {38    await findByRole("alert", { timeout: 50 });39  } catch (err) {40    missing = `rejects: ${err.message}`;41  }42  return { getByRightAway: immediate, findBy: found.name, findByNeverAppears: missing };43}

What to look for

If React warns that an update was "not wrapped in act(...)", a state update happened outside any act scope, typically an async update the test never waited for. Usually the fix is to await a findBy for the result, not to add act by hand. RTL's render and user-event already wrap their work in act.

Interactions and the network

userEvent.setup() then await user.click(), user.type(), user.keyboard() simulate the full sequence a browser produces (pointer, focus, key and input events); fireEvent dispatches a single DOM event and is a lower-level fallback. For components that fetch, mock the network layer (for example with MSW) rather than the component's own functions, so the test still exercises the real data flow.

Common mistakes

getBy to check that something is not there. It throws before your assertion runs; use queryBy and .not.toBeInTheDocument().
getBy for content that appears after a fetch. It fails immediately, as the second example models; use findBy.

Exercise · Pro

When findBy settles

Exercises are free in the first 3 lessons of every course. From here on they are part of Pro and Sprint; the lesson and its runnable examples stay open.

Upgrade