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 isolationintegration-testing- Full integration testsvcr-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