MSW (Mock Service Worker) 2.x

Network-level API mocking for frontend tests using MSW 2.x.

Quick Reference

// Core imports
import { http, HttpResponse, graphql, ws, delay, passthrough } from 'msw';
import { setupServer } from 'msw/node';

// Basic handler
http.get('/api/users/:id', ({ params }) => {
  return HttpResponse.json({ id: params.id, name: 'User' });
});

// Error response
http.get('/api/fail', () => {
  return HttpResponse.json({ error: 'Not found' }, { status: 404 });
});

// Delay simulation
http.get('/api/slow', async () => {
  await delay(2000);
  return HttpResponse.json({ data: 'response' });
});

// Passthrough (NEW in 2.x)
http.get('/api/real', () => passthrough());

Test Setup

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

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

Runtime Override

import { http, HttpResponse } from 'msw';
import { server } from '../mocks/server';

test('shows error on API failure', async () => {
  server.use(
    http.get('/api/users/:id', () => {
      return HttpResponse.json({ error: 'Not found' }, { status: 404 });
    })
  );

  render(<UserProfile id="123" />);
  expect(await screen.findByText(/not found/i)).toBeInTheDocument();
});

Anti-Patterns (FORBIDDEN)

// ❌ NEVER mock fetch directly
jest.spyOn(global, 'fetch').mockResolvedValue(...)

// ❌ NEVER mock axios module
jest.mock('axios')

// ❌ NEVER test implementation details
expect(fetch).toHaveBeenCalledWith('/api/...')

// ✅ ALWAYS use MSW
server.use(http.get('/api/...', () => HttpResponse.json({...})))

// ✅ ALWAYS test user-visible behavior
expect(await screen.findByText('Success')).toBeInTheDocument()

Key Decisions

Decision	Recommendation
Handler location	src/mocks/handlers.ts
Default behavior	Return success
Override scope	Per-test with server.use()
Unhandled requests	Error (catch missing mocks)
GraphQL	Use graphql.query/mutation
WebSocket	Use ws.link() for WS mocking

Detailed Documentation

Resource	Description
references/msw-2x-api.md	Complete MSW 2.x API reference
examples/handler-patterns.md	CRUD, auth, error, and upload examples
checklists/msw-setup-checklist.md	Setup and review checklists
scripts/handlers-template.ts	Starter template for new handlers

Related Skills

• unit-testing - Component isolation
• integration-testing - Full integration tests
• vcr-http-recording - Python equivalent

Capability Details

http-request-mocking

Keywords: http.get, http.post, http handler, REST mock Solves:

• Mock REST API endpoints
• Intercept HTTP requests at network level
• Create request handlers for testing

graphql-mocking

Keywords: graphql.query, graphql.mutation, GraphQL handler, mock GraphQL Solves:

• Mock GraphQL queries and mutations
• Handle GraphQL variables in mocks
• Test GraphQL error scenarios

websocket-mocking

Keywords: WebSocket, ws mock, real-time mock, socket mock Solves:

• Mock WebSocket connections
• Simulate real-time events
• Test WebSocket message handling

error-simulation

Keywords: error simulation, network error, 500 error, mock error Solves:

• Simulate API errors in tests
• Test error handling UI
• Mock network failures

network-delay-simulation

Keywords: delay, latency, slow response, loading state Solves:

• Simulate slow network responses
• Test loading state UI
• Verify timeout handling

runtime-handler-override

Keywords: runtime override, use.once, test-specific handler, override Solves:

• Override handlers for specific tests
• Create one-time response handlers
• Customize responses per test