用途
本技能是一份针对 Vitest 测试框架的综合性能优化与最佳实践指南，包含 8 个类别、共 44 条规则，按影响程度排序，用于指导测试编写、重构和代码审查。
适用时机
在以下场景中可参考这些指南：
- 编写新的 Vitest 测试
- 调试不稳定或运行缓慢的测试
- 配置测试环境
- 在 PR 中审查测试代码
- 从 Jest 迁移到 Vitest
- 优化 CI/CD 测试性能
规则分类（按优先级）
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 异步模式 | CRITICAL | async- |
| 2 | 测试设置与隔离 | CRITICAL | setup- |
| 3 | Mock 模式 | HIGH | mock- |
| 4 | 性能 | HIGH | perf- |
| 5 | 快照测试 | MEDIUM | snap- |
| 6 | 环境 | MEDIUM | env- |
| 7 | 断言 | LOW-MEDIUM | assert- |
| 8 | 测试组织 | LOW | org- |
快速参考
1. 异步模式（CRITICAL）
- async-await-assertions - 等待异步断言以避免误报
- async-return-promises - 从测试函数返回 Promise
- async-fake-timers - 对依赖时间的代码使用假定时器
- async-waitfor-polling - 使用 vi.waitFor 处理异步条件
- async-concurrent-expect - 在并发测试中使用测试上下文的 expect
- async-act-wrapper - 等待用户事件以避免 act 警告
- async-error-handling - 正确测试异步错误处理
2. 测试设置与隔离（CRITICAL）
- setup-beforeeach-cleanup - 在 afterEach 钩子中清理状态
- setup-restore-mocks - 每个测试后恢复 Mock
- setup-avoid-shared-state - 避免测试间共享可变状态
- setup-beforeall-expensive - 对昂贵的一次性设置使用 beforeAll
- setup-reset-modules - 测试模块状态时重置模块
- setup-test-factories - 对复杂测试数据使用测试工厂
3. Mock 模式（HIGH）
- mock-vi-mock-hoisting - 理解 vi.mock 的提升行为
- mock-spyon-vs-mock - 恰当选择 vi.spyOn 与 vi.mock
- mock-implementation-not-value - 对动态 Mock 使用 mockImplementation
- mock-msw-network - 使用 MSW 进行网络请求 Mock
- mock-avoid-overmocking - 避免过度 Mock
- mock-type-safety - 保持 Mock 的类型安全
- mock-clear-between-tests - 测试之间清除 Mock 状态
4. 性能（HIGH）
- perf-pool-selection - 为性能选择合适的 pool
- perf-disable-isolation - 在安全时禁用测试隔离
- perf-happy-dom - 尽可能使用 happy-dom 而非 jsdom
- perf-sharding - 使用分片进行 CI 并行化
- perf-run-mode-ci - 在 CI 环境中使用 run 模式
- perf-bail-fast-fail - 在 CI 中使用 bail 实现快速失败
5. 快照测试（MEDIUM）
- snap-inline-over-file - 对小值优先使用内联快照
- snap-avoid-large - 避免大型快照
- snap-stable-serialization - 确保快照序列化稳定
- snap-review-updates - 提交前审查快照更新
- snap-describe-intent - 为快照测试命名以描述意图
6. 环境（MEDIUM）
- env-per-file-override - 需要时按文件覆盖环境
- env-setup-files - 使用 setup 文件进行全局配置
- env-globals-config - 一致地配置 globals
- env-browser-api-mocking - Mock 测试环境中不可用的浏览器 API
7. 断言（LOW-MEDIUM）
- assert-specific-matchers - 使用特定匹配器而非通用匹配器
- assert-edge-cases - 测试边界情况与边界值
- assert-one-assertion-concept - 每个测试只测试一个概念
- assert-expect-assertions - 对异步测试使用 expect.assertions
- assert-toequal-vs-tobe - 正确选择 toBe 与 toEqual
8. 测试组织（LOW）
- org-file-colocation - 将测试文件与源文件放在一起
- org-describe-nesting - 使用 describe 块进行逻辑分组
- org-test-naming - 编写描述性的测试名称
- org-test-skip-only - 恰当使用 skip 和 only
使用方式
阅读各个参考文件以获取详细说明和代码示例：
- Section definitions - 类别结构与影响级别
- Rule template - 添加新规则的模板
- async-await-assertions - 示例规则文件
- mock-vi-mock-hoisting - 示例规则文件
交互与边界
- 不涵盖应用 Playwright E2E —— 临时浏览器自动化参见 playwright-v1；应用 E2E 约定位于使用方仓库规则中
- 使用 inject() 的 HTTP 应用测试与数据库隔离（PGLite、*.spec.ts 与 *.test.ts）属于使用方仓库关注点 —— 应遵循项目的 Fastify 测试规则，而非仅依赖本技能
相关技能
- TDD 方法论参见 test-tdd 技能
- 使用 MSW 进行 API Mock 参见 test-msw 技能
- TypeScript 测试模式参见 typescript 技能
完整编译文档
包含所有规则展开的完整指南：references/compiled.md