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.