Async tests and MSW: mock the network, not the fetch

findBy and waitFor: polling, not sleeping

Ten minutes from now you will know exactly why the Hook’s CI job hung, why that spinner assertion was a race, and — most importantly — why retry: 2 would have hidden all three. Each problem has a one-line diagnosis; the diagnosis only works if you understand the model.

findByRole(...) is literally getByRole wrapped in waitFor: it re-runs the query every 50 ms until it succeeds or a 1,000 ms budget burns, returning a promise. That is the entire async toolkit you need for “data appears”: await screen.findByRole("row", { name: /order #1042/i }) expresses “the user eventually sees this” with no sleep, no arbitrary delay, and a precise failure (timeout with the last query error, not a generic assertion miss). Both knobs are honest configuration, not magic: per call — findByRole("row", {}, { timeout: 3000 }) — or suite-wide via configure({ asyncUtilTimeout }) when your CI runners are genuinely slower than laptops, which they are: a 2-vCPU shared runner under parallel workers routinely takes 5–10x longer per render than a dev machine, and that multiplier is exactly what turns a comfortable 90 ms wait into a 1.3 s timeout breach.

waitFor itself has three rules that prevent the Hook’s incidents. One assertion per callback — waitFor retries until the callback stops throwing, so a callback with five expectations reports the failure of whichever ran last, and the first four re-execute on every poll. No side effects inside the callback — a fireEvent or user.click inside waitFor re-fires on every 50 ms retry; that is how the Hook’s form submitted four times and masked a dedup bug. Never empty — await waitFor(() => {}) is a sleep with extra steps; it waits exactly one tick and asserts nothing, papering over an ordering you have not understood. To assert something disappears, invert: await waitForElementToBeRemoved(() => screen.queryByRole("status")) — note queryBy, the variant that returns null instead of throwing, which is the correct probe for absence.

Asserting the loading state has its own trap: after await user.click(submit), the response may already have landed — mock servers respond in microtasks. Assert the spinner synchronously after the action that starts the request with getByRole("status") (it must be there immediately if your component renders it immediately), or add an explicit delay to the handler when the intermediate state is the thing under test.

MSW 2.x: mock the seam that does not move

Ask yourself: when the team migrates to react-query next quarter, how many tests break? If the answer depends on which mock strategy you chose, you chose the wrong seam.

Mocking fetch couples the test to a transport function. The day the team migrates from raw fetch to axios, or wraps data access in react-query, every vi.spyOn(global, "fetch") test breaks — not because behavior changed, but because the seam moved. MSW intercepts at the network boundary instead: handlers describe HTTP traffic — method, path, response — and the component under test runs its real data-fetching code, whatever that code is this quarter. The refactor from fetch to axios to react-query changes zero tests, which is the property that makes a 1,000-test suite survivable.

// handlers shared by tests and Storybook alike
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";

export const server = setupServer(
  http.get("/api/orders", () =>
    HttpResponse.json([{ id: 1042, status: "shipped" }]),
  ),
);

// test setup file
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Three load-bearing details. onUnhandledRequest: "error" turns every request you forgot to mock into a loud failure instead of a silent hang that later surfaces as a waitFor timeout — the single best flake-prevention switch in the stack. server.resetHandlers() in afterEach discards per-test overrides so one test’s 500 does not leak into the next — skipping it is a top-three source of order-dependent failures. And server.use(...) prepends handlers for the current test only:

it("shows the error boundary on a 500", async () => {
  server.use(http.get("/api/orders", () =>
    new HttpResponse(null, { status: 500 }),
  ));
  render(<Orders />);
  expect(await screen.findByRole("alert")).toHaveTextContent(/could not load/i);
});

it("treats network failure differently from a 500", async () => {
  server.use(http.get("/api/orders", () => HttpResponse.error()));
  render(<Orders />);
  expect(await screen.findByRole("alert")).toHaveTextContent(/offline/i);
});

That pair is the error-state discipline: a 500 and a network failure (HttpResponse.error()) are different user experiences — server said no versus server unreachable — and a component that collapses them into one message is a real finding, surfaced only because the seam lets you express both.

Green locally, red in CI: the timing post-mortem

Re-run the Hook’s three incidents against the rules and each one resolves. The 1.3 s render breaching a 1 s budget is not a flaky test — it is a correct test with a wrong budget for the environment; raise asyncUtilTimeout deliberately for CI-class hardware, do not sprinkle sleeps. The spinner assertion racing its own removal is an ordering bug in the test: intermediate states are asserted synchronously at the moment they must exist, or made deterministic with a delayed handler. The click-inside-waitFor is the only true defect, and it hid a production bug — which is the general lesson: most “flaky async tests” are tests that encode a wrong model of time, and the fix is never retry: 2. A useful audit heuristic for an inherited suite, in order: grep for waitFor callbacks containing more than one statement; grep for any event dispatch inside waitFor; grep for setTimeout/sleep in tests; then check whether onUnhandledRequest is set to error. Those four greps found 31 latent flakes in the Hook’s 600-test suite in an afternoon.