Testing Web

testing-web — fast, trustworthy component and hook tests

A frontend test is only worth keeping if it survives a refactor and fails for the right reason. The way to get there is boring and non-negotiable: render the thing, query it the way a user finds it, drive it with real events, and assert on what the user can see. Everything in this skill bends toward that. Tests that reach into className, state, props, or instance methods pass while the UI is broken and break while the UI is fine — delete that instinct.

What this owns / what it doesn't

This skill owns unit, component, and custom-hook tests that run in a simulated DOM (jsdom) or Vitest Browser Mode at component granularity. The moment scope crosses a boundary, switch skills:

• Real browser driving a whole app, page navigation, multi-page login-to-dashboard journeys -> ../e2e-testing/SKILL.md.
• pytest / fixtures / Python suites -> ../testing-py/SKILL.md.
• axe runs, contrast ratios, keyboard-nav auditing as the goal -> ../accessibility/SKILL.md. (You will use role queries here; auditing is not the job.)
• Render/runtime perf, re-render counts, web vitals -> ../debug/SKILL.md for diagnosis.
• How to build the component in the first place -> ../react/SKILL.md or ../nextjs/SKILL.md.

Pick the runner (do this once, never run both)

Vitest is the de-facto default for new frontend projects in 2026; Jest stays where it already lives. Jest 30 specifics (ts-jest vs babel, the jsdom v26 window.location break) live in references/jest-setup.md.

Minimal Vitest setup that works

Pin current majors: vitest ^4.0, @testing-library/react ^16.3, @testing-library/jest-dom ^6.9, @testing-library/user-event ^14.6, jsdom, @vitejs/plugin-react.

// vitest.config.ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",   // give the test a DOM; default 'node' has no document
    globals: true,          // describe/it/expect without imports; jest-dom matchers register globally
    setupFiles: ["./vitest.setup.ts"],
  },
});

// vitest.setup.ts
import "@testing-library/jest-dom/vitest"; // the /vitest entry — NOT the bare import (that is Jest's)

The /vitest import path matters: the bare @testing-library/jest-dom registers against Jest's expect. Wrong path = toBeInTheDocument is not a function.

The one rule: test what the user sees

Query and assert on the rendered output a human perceives, never the mechanism. This is what makes a test outlive a refactor — rename a state variable, swap a class library, restructure the tree, and a behavioral test still passes.

// Bad — coupled to internals; passes when broken, breaks when fine
expect(wrapper.find(".btn--loading")).toHaveLength(1);
expect(component.state.isOpen).toBe(true);

// Good — coupled to user-observable behavior
expect(screen.getByRole("button", { name: /saving/i })).toBeDisabled();
expect(screen.getByRole("dialog")).toBeVisible();

Query priority ladder

Reach for the highest query that fits. getByTestId is the fire escape, not the front door — it asserts nothing about accessibility or labels.

Pick the right variant by what you expect:

Never getBy something that arrives asynchronously — it throws before the element mounts. That is what findBy is for.

Driving interactions

Set up user-event once per test and await every interaction. It dispatches the full realistic event sequence (pointerdown -> mousedown -> focus -> mouseup -> click), so it catches handlers fireEvent silently skips.

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

it("submits the typed name", async () => {
  const user = userEvent.setup();           // call setup() before interacting
  render(<Greeter />);
  await user.type(screen.getByLabelText(/name/i), "Ada"); // await — these are async
  await user.click(screen.getByRole("button", { name: /greet/i }));
  expect(screen.getByText(/hello, ada/i)).toBeInTheDocument();
});

Reach for fireEvent only for events user-event has no verb for (e.g. scroll). A missing await is the single most common source of "passes locally, flakes in CI."

Async and the act() warning

"An update to X was not wrapped in act(...)" means state updated after your assertion ran — the test finished, the component kept working, React complained. The fix in a component test is almost never a manual act(). It is to wait for the observable result:

// Bad — asserts before the fetch resolves; state lands "outside act"
render(<Profile id="1" />);
expect(screen.getByText("Ada")).toBeInTheDocument(); // throws / act warning

// Good — findBy retries until the node appears, inside RTL's act wrapper
render(<Profile id="1" />);
expect(await screen.findByText("Ada")).toBeInTheDocument();

For a transition you can't pin to a single element, wrap the assertion in waitFor. Bare act() in a component test is a code smell — it belongs to hook tests (next section).

Testing hooks

renderHook ships inside @testing-library/react itself. Do not install or import the long-deprecated @testing-library/react-hooks. Read live values off result.current; wrap any setter call you trigger yourself in act(); re-run with new props via rerender; await async settle with waitFor.

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

it("counts down then stops at zero", async () => {
  const { result, rerender } = renderHook(({ from }) => useCountdown(from), {
    initialProps: { from: 3 },
  });
  expect(result.current.value).toBe(3);

  act(() => result.current.start());     // a setter YOU invoke -> wrap in act
  await waitFor(() => expect(result.current.value).toBe(0)); // async settle -> waitFor

  rerender({ from: 10 });                // feed new props
  expect(result.current.value).toBe(10);
});

Mocking the boundary

Mock at the edge your code talks to the outside world — the network or the imported module — never the internal function you are trying to verify. Mock the unit under test and the test proves nothing.

• Network: prefer MSW (http.get(...) handlers) so components hit a real fetch/axios path. It survives client-library swaps.
• A whole module: vi.mock("./api") (Vitest) / jest.mock("./api") (Jest) for non-network collaborators.
• Time: vi.useFakeTimers() for timers/debounce; advance with vi.advanceTimersByTime(ms), then restore in cleanup.

import { vi } from "vitest";
vi.mock("./flags", () => ({ isEnabled: () => true })); // a boundary module, not the component

Runnable copy-paste recipes — form submit, controlled input, MSW async data, a provider-wrapping custom render, fake timers, a hook with an effect + cleanup, an error-boundary test — live in references/recipes.md.

Snapshots vs assertions

Default to explicit behavioral assertions. A snapshot proves nothing about correctness — it proves output didn't change, and a giant DOM snapshot gets blindly --updated the first time it breaks. Snapshot only small, stable, serializable output (a formatted currency string, a normalized config object). Never snapshot a full component tree as your primary assertion.

Mutation: does the suite actually notice?

Coverage tells you which code ran. It cannot tell you whether any test would have noticed if that code were wrong — and a render() with no assertion, or a snapshot nobody reads, raises coverage while detecting nothing. Mutation testing plants bugs on purpose: if the suite still passes, the mutant survived and you have found a test that asserts nothing.

// stryker.config.json — scope is not optional here
{ "testRunner": "vitest", "mutate": ["src/cart/total.ts", "src/cart/discount.ts"] }

npx stryker run

Reach for the real tool over a hand-written mutant list: Stryker generates mutants from the syntax tree, so it cannot apply one to code that moved and cannot report one it never ran.

• Always scope mutate to the files you changed. A whole-project Stryker run on a real front-end does not finish in a useful amount of time; that is the main reason teams try it once and abandon it.
• Scale it to risk. Not a default toll. Run it on the logic where a bug is expensive — pricing, totals, permissions, anything money- or auth-shaped — not on presentational components, where a surviving mutant usually just means the DOM detail genuinely does not matter.
• A survivor is not automatically a failure. Some mutants are semantically equivalent to the original and cannot be killed; classify those with the reason. Never add an assertion about non-behaviour just to kill one — that is coverage-chasing wearing a different hat.
• A survivor that is a real bug gets an assertion, not an excuse. Write it, then rerun.

Anti-patterns

Verify your suite

Run the linter against a test file or directory to catch these shape violations before review:

scripts/verify.sh src/components/__tests__

It hard-fails on tests with no assertion and on un-awaited interactions, and warns on testid-first queries, raw fireEvent, stray act() in component files, and setTimeout-based waiting. It checks artifact shape, not whether your assertions are true.