msw

MSW 最佳实践

适用于 MSW v2 应用的全面 API 模拟指南（当前版本：MSW 2.15），专为 AI Agent 和大模型设计。包含 8 个类别的 48 条规则，并按影响程度排序，以指导自动化重构和代码生成。

适用场景

在以下情况下参考这些指南：

• 为测试或开发设置 MSW
• 编写或整理请求处理器
• 使用 MSW 配置测试环境
• 模拟 REST 或 GraphQL API
• 调试处理器匹配问题
• 测试错误状态和边缘情况

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	设置与初始化	严重	setup-
2	处理器架构	严重	handler-
3	测试集成	高	test-
4	响应模式	高	response-
5	请求匹配	中高	match-
6	GraphQL 模拟	中	graphql-
7	高级模式	中	advanced-
8	调试与性能	低	debug-

快速参考

1. 设置与初始化（严重）

• setup-server-node-entrypoint - 为 Node.js 使用正确的入口点（msw/node）
• setup-lifecycle-hooks - 在测试设置中配置服务生命周期
• setup-worker-script-commit - 将工作线程脚本提交到版本控制
• setup-node-version - MSW v2 要求 Node.js 18+
• setup-unhandled-requests - 配置未处理请求的行为
• setup-typescript-config - 为 MSW v2 配置 TypeScript

2. 处理器架构（严重）

• handler-happy-path-first - 将正常流程处理器定义为基准
• handler-domain-grouping - 按领域对处理器分组
• handler-absolute-urls - 在处理器中使用绝对 URL
• handler-shared-resolvers - 将共享响应逻辑提取到解析器中
• handler-v2-response-syntax - 使用 MSW v2 响应语法
• handler-request-body-parsing - 显式解析请求体
• handler-resolver-argument - 正确解构解析器参数
• handler-reusability-environments - 在不同环境间共享处理器

3. 测试集成（高）

• test-reset-handlers - 每次测试后重置处理器
• test-avoid-request-assertions - 避免直接断言请求
• test-concurrent-boundary - 在并发测试中使用 server.boundary()
• test-fake-timers-config - 配置假计时器以保留 queueMicrotask
• test-async-utilities - 使用异步测试工具处理模拟响应
• test-clear-request-cache - 在测试之间清除请求库缓存
• test-jsdom-environment - 为 Jest 使用正确的 JSDOM 环境

4. 响应模式（高）

• response-http-response-helpers - 使用 HttpResponse 静态方法
• response-delay-realistic - 仅在测试计时行为时添加延迟
• response-error-simulation - 正确模拟错误响应
• response-one-time-handlers - 在顺序场景中使用一次性处理器
• response-custom-headers - 正确设置响应标头
• response-streaming - 使用 ReadableStream 模拟流式响应

5. 请求匹配（中高）

• match-url-patterns - 正确使用 URL 路径参数
• match-query-params - 从请求 URL 获取查询参数
• match-custom-predicate - 对复杂匹配使用自定义谓词
• match-http-methods - 显式匹配 HTTP 方法
• match-handler-order - 按从具体到通用的顺序排列处理器

6. GraphQL 模拟（中）

• graphql-operation-handlers - 使用操作名称进行 GraphQL 匹配
• graphql-error-responses - 以正确格式返回 GraphQL 错误
• graphql-batched-queries - 处理批量 GraphQL 查询
• graphql-variables-access - 正确访问 GraphQL 变量
• graphql-schema-first - 根据 GraphQL 架构解析操作

7. 高级模式（MEDIUM）

• advanced-bypass-requests - 使用 bypass() 发送直通请求
• advanced-cookies-auth - 处理 Cookie 和身份验证
• advanced-dynamic-scenarios - 实现动态模拟场景
• advanced-vitest-browser - 为 Vitest 浏览器模式配置 MSW
• advanced-file-uploads - 模拟文件上传端点
• advanced-websocket-mocking - 使用 ws.link 模拟 WebSocket 连接
• advanced-playwright-integration - 使用 @msw/playwright 中的 defineNetworkFixture

8. 调试与性能（LOW）

• debug-lifecycle-events - 使用生命周期事件进行调试
• debug-verify-interception - 验证请求拦截是否正常工作
• debug-common-issues - 了解 MSW 常见问题及其修复方法
• debug-request-logging - 记录请求详情以便调试

使用方法

先在项目根目录运行：

npx -y @pymodel/react-frontend-skills detect            # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill msw  # deprecated APIs → rule IDs

针对上方与任务匹配的每条规则以及每个 scan 命中项，阅读 references/<rule-id>.md，了解其重要性，以及错误与正确的代码示例。

相关技能

• 如需使用模拟 API，请参阅 tanstack-query 技能
• 如需了解测试框架模式，请参阅 vitest；如需了解方法论，请参阅 tdd