MSW (Mock Service Worker)

An API mocking library that intercepts network requests at the Service Worker level in browsers and via a Node.js interception layer in tests. Define request handlers once and use them across your browser dev environment, Jest, and Vitest test suites — no application code changes needed.

What is MSW?

Mock Service Worker is an API mocking library that sits at the network layer rather than patching your HTTP client. In the browser, it registers a Service Worker that intercepts outgoing requests before they leave the browser tab. In Node.js environments (Jest, Vitest, server-side rendering), it uses a lower-level HTTP interception layer with the same API.

The key advantage is that your application code is unaware of the mocking. Whether your app uses fetch, axios, ky, or any other library, MSW handlers intercept the requests transparently. This makes MSW mocks more realistic — the app goes through the same code path as it would with a real API.

Key Features

• Network-level interception — intercepts at the Service Worker or Node.js HTTP level, not by patching fetch/axios
• Shared handlers — define handlers once in a handlers.ts file; use the same handlers in browser dev and Node.js tests
• REST and GraphQL — first-class support for both REST (http.get, http.post, etc.) and GraphQL (graphql.query, graphql.mutation)
• One-time overrides — use server.use() inside a test to override a handler for that test only; automatically cleaned up after
• Request passthrough — use passthrough() to let certain requests reach the real API while mocking others
• Response streaming — simulate streamed responses (e.g., SSE, chunked transfers) with ReadableStream bodies
• TypeScript native — full TypeScript support for request body types, route params, and response types

Installation

# Install MSW
npm install msw --save-dev

# Initialize the Service Worker file for browser usage
npx msw init public/ --save

# The above copies mockServiceWorker.js into your public directory
# Add "workerDirectory": "public" to package.json msw config if needed

Defining REST Handlers

Define handlers using http.get(), http.post(), and other HTTP method helpers. Return HttpResponse.json() for JSON responses or construct a custom HttpResponse for other status codes.

// src/mocks/handlers.ts
import { http, HttpResponse } from 'msw';

export const handlers = [
  // GET /api/users — return a list of users
  http.get('/api/users', () => {
    return HttpResponse.json([
      { id: 1, name: 'Alice', email: '[email protected]' },
      { id: 2, name: 'Bob',   email: '[email protected]'   },
    ]);
  }),

  // POST /api/users — create a user and echo it back
  http.post('/api/users', async ({ request }) => {
    const body = await request.json() as { name: string; email: string };
    return HttpResponse.json(
      { id: Date.now(), ...body },
      { status: 201 }
    );
  }),

  // Simulate a 404 for a missing resource
  http.get('/api/users/:id', ({ params }) => {
    if (Number(params.id) > 100) {
      return new HttpResponse(null, { status: 404 });
    }
    return HttpResponse.json({ id: params.id, name: 'Alice' });
  }),
];

Browser Setup

Set up the Service Worker with setupWorker() from msw/browser. Start it conditionally in development so it never activates in production builds.

// src/mocks/browser.ts — browser setup
import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';

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

// src/main.tsx (or index.tsx) — start the worker in development
async function enableMocking() {
  if (process.env.NODE_ENV !== 'development') return;

  const { worker } = await import('./mocks/browser');
  // Start the Service Worker; onUnhandledRequest warns about missing handlers
  return worker.start({ onUnhandledRequest: 'warn' });
}

enableMocking().then(() => {
  ReactDOM.createRoot(document.getElementById('root')!).render();
});

Node.js Setup (Tests)

For tests, use setupServer() from msw/node. Start, reset, and stop the server in your test setup file. Call server.resetHandlers() after each test to remove any per-test overrides.

// src/mocks/node.ts — Node.js setup (for tests)
import { setupServer } from 'msw/node';
import { handlers } from './handlers';

export const server = setupServer(...handlers);

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

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());  // reset overrides between tests
afterAll(() => server.close());

One-Time Handler Overrides

Use server.use() inside a test to temporarily override a handler for that test only. This is the standard pattern for testing error states, empty responses, and edge cases.

// One-time handler override inside a specific test
import { http, HttpResponse } from 'msw';
import { server } from '../mocks/node';
import { render, screen, waitFor } from '@testing-library/react';
import UserList from './UserList';

test('shows an error when the API fails', async () => {
  // Override for this test only — resets after the test via afterEach
  server.use(
    http.get('/api/users', () => {
      return new HttpResponse(null, { status: 500 });
    })
  );

  render();

  await waitFor(() => {
    expect(screen.getByText('Failed to load users')).toBeInTheDocument();
  });
});

GraphQL Handlers

Import graphql from msw and define handlers by operation name. Works for any GraphQL client — Apollo, urql, or raw fetch.

// GraphQL handler with MSW
import { graphql, HttpResponse } from 'msw';

export const graphqlHandlers = [
  graphql.query('GetUser', ({ variables }) => {
    return HttpResponse.json({
      data: {
        user: {
          id: variables.id,
          name: 'Alice',
          email: '[email protected]',
        },
      },
    });
  }),

  graphql.mutation('CreateUser', ({ variables }) => {
    return HttpResponse.json({
      data: {
        createUser: { id: '99', ...variables.input },
      },
    });
  }),
];

Pros and Cons