⚡

MSW模拟服务技能Skill msw

这个技能提供MSW（模拟服务工作者）的最佳实践指南，用于在测试中模拟HTTP和GraphQL API。它涵盖设置、处理器架构、测试集成等关键方面，适用于前端和后端开发中的API mocking，以提升测试效率和代码质量。关键词：MSW, API模拟, 测试, HTTP mocking, GraphQL mocking, 前端测试, 后端测试。

测试 0 次安装 0 次浏览 更新于 3/18/2026

name: msw description: MSW（模拟服务工作者）用于测试中API模拟的最佳实践（原名为test-msw）。此技能应在设置MSW、编写请求处理器或模拟HTTP API时使用。此技能不涵盖通用测试模式（请使用test-vitest或test-tdd技能）或测试方法学。

MSW最佳实践

全面的MSW v2应用API模拟指南，专为AI代理和LLMs设计。包含8个类别的45条规则，按影响优先级排序，以指导自动化重构和代码生成。

何时应用

参考这些准则当：

  • 为测试或开发设置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 - 将worker脚本提交到版本控制
  • setup-node-version - 要求Node.js 18+以支持MSW v2
  • 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变量

7. 高级模式（中）

  • advanced-bypass-requests - 使用bypass()传递请求
  • advanced-cookies-auth - 处理Cookie和认证
  • advanced-dynamic-scenarios - 实现动态模拟场景
  • advanced-vitest-browser - 为Vitest浏览器模式配置MSW
  • advanced-file-uploads - 模拟文件上传端点

8. 调试与性能（低）

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

如何使用

阅读个别参考文件获取详细解释和代码示例：

  • 章节定义 - 类别结构和影响级别
  • 规则模板 - 添加新规则的模板
  • 个别规则：references/{prefix}-{slug}.md

相关技能

  • 用于从OpenAPI生成MSW模拟，见orval技能
  • 用于消费模拟API，见tanstack-query技能
  • 用于测试方法学，见test-vitest或test-tdd技能

完整编译文档

获取带所有规则扩展的完整指南：AGENTS.md