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