tech-vitest

Vitest 测试框架

快速、由 Vite 驱动的测试框架，提供兼容 Jest 的 API 和原生 ESM。Vitest 擅长：

• 监听模式 — 借助智能文件监听，在开发过程中即时反馈
• 原生 TypeScript/JSX — 由 Vite 编译，无需额外设置
• 模拟生态系统 — 使用 vi.mock() 模拟模块，使用 MSW v2 处理 HTTP 请求，使用假计时器测试依赖时间的代码
• 快照测试 — 自动管理快照，并支持内联快照
• 并发测试 — 并行执行测试，并提供适当的隔离

核心挑战：测试隔离。Vitest 对 vi.mock() 的提升规则要求使用 vi.hoisted() 管理共享模拟状态。MSW v2 更改了处理器 API。更新快照时必须谨慎。

工作流

设置测试或添加测试用例时：

1. 明确范围 — 要测试什么行为？（单元／集成／端到端？）
2. 确定依赖项 — 是否涉及 HTTP、计时器或其他模块？
3. 选择策略 — 使用 vi.mock() 和提升规则模拟模块，使用 MSW 处理 HTTP，使用假计时器处理时间
4. 提升共享状态 — 如果模拟需要访问测试作用域中的变量，请使用 vi.hoisted()
5. 设置处理器 — 在 beforeAll() 中启动 MSW 服务，并在 afterEach() 中重置
6. 断言和快照 — 使用匹配器；仅对稳定输出创建快照
7. 验证 — 运行 vitest --watch 并检查覆盖率

规则

测试按关注点组织：

• 模拟模块 — vi.mock()、vi.hoisted()，以及使用 importOriginal 进行部分模拟
• 模拟函数 — 使用 vi.fn() 设置返回值、实现和调用跟踪
• 监视方法 — 使用 vi.spyOn() 监视对象方法而不替换它们
• 模拟 HTTP — MSW v2 处理器、setupServer()、按测试覆盖处理器
• 假计时器 — vi.useFakeTimers()、vi.setSystemTime()、推进计时器
• 快照 — toMatchSnapshot()、内联快照、边界情况
• 断言 — 为测试断言选择匹配器
• 钩子和设置 — beforeEach、afterEach、测试夹具、设置文件

请参阅 rules/，了解实现模式和示例。

示例

正向触发

用户：“在这个 Vitest 测试中模拟 API 客户端，让它返回一个虚假响应。”

预期行为：使用 tech-vitest 指南，遵循 vi.mock() 的提升规则和 MSW 模式。

不触发

用户：“为用户账户设置 PostgreSQL 数据库架构。”

预期行为：不要优先使用 tech-vitest；选择更相关的技能，或不使用该技能。

• 错误：在条件语句中调用 vi.mock()

• 原因：vi.mock() 会被提升；条件会被忽略，导致模块状态异常

• 解决方案：将模拟移到文件顶部；使用 vi.hoisted() 管理条件模拟状态

• 错误：未经检查就更新快照

• 原因：快照会绕过断言，意外更改可能掩盖错误

• 解决方案：在 --ui 模式下始终检查差异，再使用 -u 接受更改

故障排除

• 错误：Cannot access 'mockData' before initialization

• 原因：在 vi.mock() 外部定义的变量无法在工厂函数中访问（提升导致）

• 解决方案：使用 vi.hoisted() 在顶层定义共享模拟状态

• 错误：从未调用模拟处理器；实际 HTTP 请求被发送

• 原因：MSW 服务未启动，或处理器方法错误（http 或 graphql）

• 解决方案：在 beforeAll() 中调用 server.listen()；确认处理器动词与请求匹配

• 错误：测试在本地通过，但在 CI 中失败

• 原因：测试之间未重置假计时器；时间在整个测试套件中不断偏移

• 解决方案：务必在 afterEach() 中调用 vi.useRealTimers()