Back to Details

msw-mocking

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MSW (Mock Service Worker) 2.x

MSW (Mock Service Worker) 2.x

Network-level API mocking for frontend tests using MSW 2.x.
为前端测试提供网络层面的API模拟方案，基于MSW 2.x实现。

Quick Reference

快速参考

typescript
// 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());
typescript
// 核心导入
import { http, HttpResponse, graphql, ws, delay, passthrough } from 'msw';
import { setupServer } from 'msw/node';

// 基础处理器
http.get('/api/users/:id', ({ params }) => {
  return HttpResponse.json({ id: params.id, name: 'User' });
});

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

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

// 请求透传（2.x 新增功能）
http.get('/api/real', () => passthrough());

Test Setup

测试设置

typescript
// 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());
typescript
// 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

运行时覆盖

typescript
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();
});
typescript
import { http, HttpResponse } from 'msw';
import { server } from '../mocks/server';

test('当API失败时显示错误', 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)

反模式（禁止使用）

typescript
// ❌ 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()
typescript
// ❌ 绝不要直接mock fetch
jest.spyOn(global, 'fetch').mockResolvedValue(...)

// ❌ 绝不要mock axios模块
jest.mock('axios')

// ❌ 绝不要测试实现细节
expect(fetch).toHaveBeenCalledWith('/api/...')

// ✅ 始终使用MSW
server.use(http.get('/api/...', () => HttpResponse.json({...})))

// ✅ 始终测试用户可见的行为
expect(await screen.findByText('Success')).toBeInTheDocument()

Key Decisions

关键决策

DecisionRecommendation
Handler location
src/mocks/handlers.ts
Default behaviorReturn success
Override scopePer-test with 
server.use()
Unhandled requestsError (catch missing mocks)
GraphQLUse 
graphql.query/mutation
WebSocketUse 
ws.link()
for WS mocking
决策项推荐方案
处理器位置
src/mocks/handlers.ts
默认行为返回成功响应
覆盖范围通过
server.use()
在单测中单独设置
未处理请求抛出错误（捕获缺失的模拟）
GraphQL使用
graphql.query/mutation
WebSocket使用
ws.link()
进行WS模拟

Detailed Documentation

详细文档

ResourceDescription
references/msw-2x-api.mdComplete MSW 2.x API reference
examples/handler-patterns.mdCRUD, auth, error, and upload examples
checklists/msw-setup-checklist.mdSetup and review checklists
scripts/handlers-template.tsStarter template for new handlers
资源描述
references/msw-2x-api.md完整的MSW 2.x API参考文档
examples/handler-patterns.mdCRUD、认证、错误和上传等场景示例
checklists/msw-setup-checklist.md安装和检查清单
scripts/handlers-template.ts新处理器的起始模板

Related Skills

相关技能

  • unit-testing
    - Component isolation
  • integration-testing
    - Full integration tests
  • vcr-http-recording
    - Python equivalent
  • unit-testing
    - 组件隔离
  • integration-testing
    - 完整集成测试
  • vcr-http-recording
    - Python中的同类工具

Capability Details

功能详情

http-request-mocking

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
关键词: http.get, http.post, http handler, REST mock 解决问题:
  • 模拟REST API端点
  • 在网络层面拦截HTTP请求
  • 创建用于测试的请求处理器

graphql-mocking

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
关键词: graphql.query, graphql.mutation, GraphQL handler, mock GraphQL 解决问题:
  • 模拟GraphQL查询和变更
  • 在模拟中处理GraphQL变量
  • 测试GraphQL错误场景

websocket-mocking

websocket-mocking

Keywords: WebSocket, ws mock, real-time mock, socket mock Solves:
  • Mock WebSocket connections
  • Simulate real-time events
  • Test WebSocket message handling
关键词: WebSocket, ws mock, real-time mock, socket mock 解决问题:
  • 模拟WebSocket连接
  • 模拟实时事件
  • 测试WebSocket消息处理

error-simulation

error-simulation

Keywords: error simulation, network error, 500 error, mock error Solves:
  • Simulate API errors in tests
  • Test error handling UI
  • Mock network failures
关键词: error simulation, network error, 500 error, mock error 解决问题:
  • 在测试中模拟API错误
  • 测试错误处理UI
  • 模拟网络故障

network-delay-simulation

network-delay-simulation

Keywords: delay, latency, slow response, loading state Solves:
  • Simulate slow network responses
  • Test loading state UI
  • Verify timeout handling
关键词: delay, latency, slow response, loading state 解决问题:
  • 模拟缓慢的网络响应
  • 测试加载状态UI
  • 验证超时处理

runtime-handler-override

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
关键词: runtime override, use.once, test-specific handler, override 解决问题:
  • 为特定测试覆盖处理器
  • 创建一次性响应处理器
  • 为每个测试自定义响应