API Mocking with MSW skill for Codex

Mock at the network, not the client: tests then exercise the real fetch or axios code, headers, serialisation and error handling. A good setup fails loudly on any unmocked request, keeps one set of happy-path handlers shared by tests, Storybook and local dev, and lets each test override only the response it is about.

Inspect first

1. Read AGENTS.md and package.json: MSW version (msw@^2 assumed below), test runner (Vitest, Jest), environment (jsdom, happy-dom, node), Storybook presence.
2. Find existing mocks: rg -n "msw|setupServer|jest.mock\(.*(axios|fetch)|vi.mock\(|nock\(" -g '!node_modules'.
3. Find the API contract: OpenAPI spec, generated client types, GraphQL schema. Mocks typed against it catch drift; hand-written shapes rot.
4. Installing MSW needs network; MSW 2 needs Node 18+.

When MSW is the right tool

Situation	Use
Frontend or Node code using fetch, axios, ky, Apollo, urql	MSW
Python with requests	responses
Python with httpx	respx
Node legacy http module code, or MSW cannot be added	nock
JVM services, or language-agnostic stub server in Docker	WireMock
Verifying the mock matches the provider	Contract tests (contract-testing), not more mocks
You own the backend and can run it	Integration test against the real service (integration-testing)

Do not mock your own module boundaries with MSW to avoid writing a unit test seam. MSW is for HTTP you do not control in that test.

Layout

src/mocks/
├── handlers.ts        # happy-path handlers, one per endpoint
├── data.ts            # typed fixture builders (or factories)
├── node.ts            # setupServer(...handlers) for tests and Node
└── browser.ts         # setupWorker(...handlers) for dev and Storybook

// src/mocks/handlers.ts
import { http, HttpResponse, graphql, delay } from "msw";
import type { components } from "../api/schema";   // openapi-typescript output
type User = components["schemas"]["User"];

export const handlers = [
  http.get("/api/users/:id", ({ params }) => {
    return HttpResponse.json<User>({ id: String(params.id), name: "Ada Lovelace", role: "admin" });
  }),
  http.post("/api/orders", async ({ request }) => {
    const body = (await request.json()) as { items: unknown[] };
    if (!body.items?.length) {
      return HttpResponse.json({ type: "about:blank", title: "No items" }, { status: 422 });
    }
    return HttpResponse.json({ id: "ord_1", status: "pending" }, { status: 201 });
  }),
  graphql.query("GetCart", () => HttpResponse.json({ data: { cart: { items: [] } } })),
];

// src/mocks/node.ts
import { setupServer } from "msw/node";
import { handlers } from "./handlers";
export const server = setupServer(...handlers);

Test lifecycle

// vitest.setup.ts (or jest.setup.ts)
import { beforeAll, afterEach, afterAll } from "vitest";
import { server } from "./src/mocks/node";

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

onUnhandledRequest: "error" is non-negotiable: without it a missing handler silently hits the network or hangs.

Per-test overrides

import { http, HttpResponse, delay } from "msw";
import { server } from "../mocks/node";

it("shows a retry button when the profile request fails", async () => {
  server.use(http.get("/api/users/:id", () => HttpResponse.json({ title: "boom" }, { status: 500 })));
  render(<Profile id="42" />);
  expect(await screen.findByRole("button", { name: /retry/i })).toBeVisible();
});

it("shows a spinner while loading", async () => {
  server.use(http.get("/api/users/:id", async () => { await delay(200); return HttpResponse.json({ id: "42", name: "A", role: "member" }); }));
  render(<Profile id="42" />);
  expect(screen.getByRole("progressbar")).toBeVisible();
});

Scenario	Handler body
HTTP error	HttpResponse.json(problem, { status: 503 })
Network failure (fetch rejects)	HttpResponse.error()
Slow response	await delay(ms); delay("infinite") for a hanging request
First call fails, retry succeeds	first server.use(http.get(url, failing, { once: true })) then shared handler applies
Let a request reach the real server	passthrough() (rarely right in tests)

Asserting on requests

Prefer asserting on the UI or return value. When the request itself is the behaviour (an analytics call, the exact payload sent), capture it inside the handler:

let sent: unknown;
server.use(http.post("/api/orders", async ({ request }) => {
  sent = await request.json();
  return HttpResponse.json({ id: "ord_1", status: "pending" }, { status: 201 });
}));
await submitOrder();
expect(sent).toEqual({ items: [{ sku: "A1", qty: 2 }] });

Browser, dev and Storybook

npx msw init public/ --save    # writes mockServiceWorker.js and records the dir in package.json

Start the worker before rendering, only in development:

if (import.meta.env.DEV && import.meta.env.VITE_MOCK_API === "true") {
  const { worker } = await import("./mocks/browser");
  await worker.start({ onUnhandledRequest: "bypass" });
}

For Storybook, msw-storybook-addon lets each story set parameters.msw.handlers. Commit mockServiceWorker.js and regenerate it when MSW is upgraded.

Migrating MSW 1 to 2

MSW 1	MSW 2
rest.get(url, (req, res, ctx) => res(ctx.json(x)))	http.get(url, () => HttpResponse.json(x))
ctx.status(500)	{ status: 500 } as the init argument
req.params, req.body	({ params, request }), await request.json()
ctx.delay()	await delay()
res.once(...)	{ once: true } handler option
res.networkError()	HttpResponse.error()

Community codemods exist, but review every changed handler; resolver arguments changed shape and response bodies are now standard Fetch API Response objects.

Verification

• Delete a handler and confirm the test fails with MSW’s unhandled request error.
• Change a field name in the real API types; typed handlers must fail to compile.
• Run tests with the network disabled (Codex sandboxes often are); nothing should time out.

Gotchas

• Jest with jsdom lacks the Fetch API globals MSW 2 needs (TextEncoder, Response, ReadableStream). Use testEnvironment: "jest-fixed-jsdom" or switch to Vitest.
• Relative URLs in Node have no origin. Use the absolute base URL the client uses, or a path pattern that matches any origin (*/api/users/:id).
• server.use overrides leak into later tests if resetHandlers() is missing.
• Mocks drift from the real API silently. Type them from the schema and add contract tests for the endpoints that matter.
• Mocking fetch with vi.fn() and also running MSW means MSW never sees the request.