MSW (Mock Service Worker)

Overview

Mock Service Worker (MSW) was created by Artem Zakharchenko in 2019 and has become the de facto standard for API mocking in the JavaScript ecosystem. Instead of monkey-patching fetch or wrapping axios, MSW registers a Service Worker in the browser that acts as a network-level proxy. In Node.js (for Jest or Vitest tests), MSW uses an interceptor layer instead of a Service Worker — but the handler API is identical. You write your mock handlers once and they work in both environments.

MSW version 2 (released late 2023) introduced a cleaner handler API with http and HttpResponse, better TypeScript support, and first-class ESM compatibility. Version 2 is the current standard and what this page documents.

Why MSW beats manual mocks

Manual mocks duplicate knowledge. You write both the real API call and the mock in two places. When the real API changes, the mock silently lies — your tests keep passing while the actual integration is broken. This false confidence is worse than no mock at all.

MSW intercepts at the network level. Your component code calls fetch or axios exactly as it would in production. MSW intercepts the request before it leaves the browser. Your tests exercise the real request-making logic — the same headers, the same error handling, the same retry logic — because nothing about the call path changes. Only the response is substituted.

When to use MSW

Setup in 5 minutes

Install MSW as a dev dependency:

npm install msw --save-dev

Define your handlers in a central file. Handlers describe which requests to intercept and what response to return:

// src/mocks/handlers.js
import { http, HttpResponse } from "msw";

export const handlers = [
  // GET — return a KiwiSaver balance
  http.get("https://api.example.co.nz/kiwisaver/balance", () => {
    return HttpResponse.json({
      balance: 45230.87,
      lastUpdated: "2026-06-27",
      memberId: "KS-123456"
    });
  }),

  // POST — validate a contribution and return a transaction ID
  http.post("https://api.example.co.nz/kiwisaver/contribution", async ({ request }) => {
    const body = await request.json();
    if (!body.amount || body.amount <= 0) {
      return new HttpResponse(null, { status: 422 });
    }
    return HttpResponse.json({ success: true, transactionId: "TXN-789" });
  }),
];

For Jest / Vitest (Node.js environment), set up a server in your test setup file:

// src/mocks/server.js
import { setupServer } from "msw/node";
import { handlers } from "./handlers";

// This server starts/stops around each test suite automatically
export const server = setupServer(...handlers);

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

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

For the browser (development workflow with Vite or CRA), initialise a Service Worker:

// Generate the Service Worker file (run once)
npx msw init public/ --save

// src/mocks/browser.js
import { setupWorker } from "msw/browser";
import { handlers } from "./handlers";

export const worker = setupWorker(...handlers);

// src/main.js — start the worker in development only
if (import.meta.env.DEV) {
  const { worker } = await import("./mocks/browser");
  await worker.start();
}

NZ-specific use case: ACC portal claims API

The ACC Claims Management System exposes a /api/claims/status endpoint that returns the current state of an injury claim. During development, this API may not yet exist, or the backend team may not have finished implementing all status transitions. MSW lets the frontend team build and test the claims status UI in full, against all possible states, before the real API is available.

Define handlers that return different claim states based on the claim ID in the request URL:

// src/mocks/handlers.js
import { http, HttpResponse } from "msw";

const claimFixtures = {
  "CLM-001": { claimId: "CLM-001", status: "Pending",       label: "Claim received — awaiting assessment" },
  "CLM-002": { claimId: "CLM-002", status: "Under Review",  label: "Being assessed by an ACC case manager" },
  "CLM-003": { claimId: "CLM-003", status: "Approved",      label: "Claim accepted. Weekly compensation active." },
  "CLM-004": { claimId: "CLM-004", status: "Declined",      label: "Claim declined. See letter for details." },
};

export const handlers = [
  http.get("/api/claims/status/:claimId", ({ params }) => {
    const claim = claimFixtures[params.claimId];
    if (!claim) {
      return new HttpResponse(null, { status: 404 });
    }
    return HttpResponse.json(claim);
  }),
];

Test that the UI renders the correct status badge for each claim state:

// ClaimStatus.test.jsx
import { render, screen } from "@testing-library/react";
import { ClaimStatus } from "./ClaimStatus";

// The MSW server is running via vitest.setup.js — no extra setup needed here.

const statusCases = [
  { claimId: "CLM-001", expectedBadge: "Pending" },
  { claimId: "CLM-002", expectedBadge: "Under Review" },
  { claimId: "CLM-003", expectedBadge: "Approved" },
  { claimId: "CLM-004", expectedBadge: "Declined" },
];

test.each(statusCases)(
  "renders $expectedBadge badge for claim $claimId",
  async ({ claimId, expectedBadge }) => {
    render(<ClaimStatus claimId={claimId} />);
    // The component calls fetch("/api/claims/status/CLM-001") — MSW intercepts it
    const badge = await screen.findByRole("status");
    expect(badge).toHaveTextContent(expectedBadge);
  }
);

The component's fetch call runs unchanged. MSW intercepts the network request, returns the fixture, and the test asserts on what the user actually sees. When the real ACC API is ready, you point the component at it and remove the handler — the tests remain valid because they tested the component, not the mock.

MSW vs WireMock

Pros & Cons

Platforms & Integrations

MSW runs on Windows, macOS, and Linux. It is a JavaScript-only library with no runtime dependencies.

Pricing

NZ Context

MSW is increasingly common in NZ frontend teams using React or Vue. Teams building portals for government agencies (MSD, ACC, IRD) often use MSW to develop and test against simulated API responses while backend contracts are still being negotiated under the GCDO API standard. For NZ QA engineers working in JavaScript stacks, understanding MSW is a practical advantage — it is the test infrastructure you will encounter when joining a React-based project at companies like Xero, Trade Me, or ANZ Digital.

Alternatives

• WireMock — Stateful HTTP mock server, best for Java/Spring Boot. Runs as a separate process. Better for full integration test suites.
• json-server — Quickly spin up a REST API from a JSON file. Stateful but not production-identical; no request interception.
• Mirage JS — In-browser API mocking with an ORM-like model layer. Good for prototyping but heavier than MSW and less maintained.
• Nock — Node.js HTTP mocking library. Intercepts Node.js HTTP/HTTPS calls. Does not work in the browser; no shared handler file.

Self-check

Click each question to reveal the answer.

Learn more

• MSW Official Site
• MSW Documentation
• MSW on GitHub
• React Testing Library + MSW example
• Vitest Mocking Guide