MSW (Mock Service Worker) Guide

The complete reference for Mock Service Worker (MSW) — the network-level API mocking library trusted by the React, Testing Library, and Storybook communities. Covers handlers, browser and Node.js setup, GraphQL mocking, and testing strategies.

What is Mock Service Worker?

Mock Service Worker (MSW) is an API mocking library that operates at the network layer rather than patching JavaScript modules. Traditional mocking libraries replace fetch or axios with a mock implementation — which means your tests use a different code path than your production app. MSW takes a different approach: your application code calls fetch('/api/users') normally, and MSW intercepts that real HTTP request before it reaches the network.

In the browser, MSW registers a Service Worker that intercepts outgoing requests. In Node.js (Jest, Vitest), it patches the built-in http module. Crucially, both environments use the same handler syntax — define your mock API once in a handlers.ts file and reuse it in development (browser), unit tests (Vitest/Jest), and integration tests (Playwright). This eliminates the drift between test mocks and production behaviour.

Installation

# Install MSW
npm install msw --save-dev

# Initialize the service worker file (browser)
npx msw init public/ --save

# Verify the service worker is in public/
ls public/mockServiceWorker.js

Defining Request Handlers

Handlers are the heart of MSW. Define them in a shared file so they can be imported by both the browser worker and the Node.js server.

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

export const handlers = [
  // GET request — return JSON
  http.get('/api/users', () => {
    return HttpResponse.json([
      { id: 1, name: 'Alice', role: 'admin' },
      { id: 2, name: 'Bob', role: 'user' },
    ]);
  }),

  // GET with URL params
  http.get('/api/users/:id', ({ params }) => {
    const { id } = params;
    if (id === '999') {
      return HttpResponse.json({ message: 'User not found' }, { status: 404 });
    }
    return HttpResponse.json({ id: Number(id), name: 'Alice' });
  }),

  // POST — read request body
  http.post('/api/users', async ({ request }) => {
    const body = await request.json() as { name: string; email: string };
    return HttpResponse.json({ id: 3, ...body }, { status: 201 });
  }),

  // Simulate slow API
  http.get('/api/slow-endpoint', async () => {
    await delay(2000);
    return HttpResponse.json({ data: 'delayed response' });
  }),

  // Simulate network failure
  http.get('/api/broken', () => {
    return HttpResponse.error();
  }),
];

Browser Setup: setupWorker

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

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

// src/main.tsx — start only in development
async function enableMocking() {
  if (process.env.NODE_ENV !== 'development') return;
  const { worker } = await import('./mocks/browser');
  return worker.start({
    onUnhandledRequest: 'warn', // Warn on unmocked requests
  });
}

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

Node.js Setup: setupServer (Jest/Vitest)

// src/mocks/server.ts
import { setupServer } from 'msw/node';
import { handlers } from './handlers';

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

// tests/setup.ts — configure in vitest.config.ts or jest.config.ts
import { server } from '../src/mocks/server';
import { afterAll, afterEach, beforeAll } from 'vitest'; // or jest

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers()); // Reset per-test overrides
afterAll(() => server.close());

Testing Different API States

import { render, screen, waitFor } from '@testing-library/react';
import { server } from '../mocks/server';
import { http, HttpResponse } from 'msw';
import { UserList } from './UserList';

describe('UserList', () => {
  it('displays users from API', async () => {
    render(<UserList />);
    await waitFor(() => {
      expect(screen.getByText('Alice')).toBeInTheDocument();
      expect(screen.getByText('Bob')).toBeInTheDocument();
    });
  });

  it('shows empty state when no users', async () => {
    // Override handler for this specific test
    server.use(
      http.get('/api/users', () => HttpResponse.json([]))
    );
    render(<UserList />);
    await waitFor(() => {
      expect(screen.getByText('No users found')).toBeInTheDocument();
    });
  });

  it('shows error state on server failure', async () => {
    server.use(
      http.get('/api/users', () =>
        HttpResponse.json({ message: 'Server error' }, { status: 500 })
      )
    );
    render(<UserList />);
    await waitFor(() => {
      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
    });
  });
});

GraphQL Mocking

import { graphql, HttpResponse } from 'msw';

export const handlers = [
  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 },
      },
    });
  }),
];

Key Features

• Network-level interception — works with any HTTP client: fetch, axios, ky, SWR, React Query
• Unified handler syntax — same handlers.ts used in browser dev and Node.js tests
• REST and GraphQL — first-class support for both API styles
• Response utilities — HttpResponse.json(), delay(), error(), network simulation
• Per-test overrides — server.use() overrides specific handlers for edge case tests
• TypeScript first — fully typed request params, body, and response
• Storybook integration — use MSW handlers as mock API in stories

Comparison: MSW vs Alternatives

Pros & Cons