vitest

Vitest 最佳实践

兼容 Vitest 5 的测试指南，包含 8 个类别中的 46 条规则。Vitest 5 要求 Node.js 22.12+ 和 Vite 6.4+；Vitest 4.1 仍提供向后移植支持。

适用场景

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

• 编写新的 Vitest 测试
• 调试不稳定或缓慢的测试
• 设置测试配置
• 在 PR 中审查测试代码
• 从 Jest 迁移到 Vitest
• 优化 CI/CD 测试性能

文档所述迁移差异之外的 Jest 专用 API 和配置不在本指南范围内；仍由 Jest 运行的测试请参阅 Jest 自身的文档。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	异步模式	严重	async-
2	测试设置与隔离	严重	setup-
3	模拟模式	高	mock-
4	性能	高	perf-
5	快照测试	中	snap-
6	环境	中	env-
7	断言	低至中	assert-
8	测试组织	低	org-

快速参考

1. 异步模式（严重）

• async-await-assertions - 等待异步断言（Vitest 5 会因未等待的断言而失败）
• async-return-promises - 从测试函数返回 Promise
• async-fake-timers - 对依赖时间的代码使用伪计时器
• async-waitfor-polling - 使用 vi.waitFor 检查异步条件
• async-concurrent-expect - 在并发测试中使用测试上下文的 expect
• async-act-wrapper - 等待用户事件，避免出现 act 警告
• async-error-handling - 正确测试异步错误处理

2. 测试设置与隔离（严重）

• setup-beforeeach-cleanup - 在 afterEach 钩子中清理状态
• setup-restore-mocks - 每次测试后恢复模拟
• setup-avoid-shared-state - 避免测试之间共享可变状态
• setup-beforeall-expensive - 对耗时的一次性设置使用 beforeAll
• setup-reset-modules - 测试模块状态时重置模块
• setup-test-factories - 使用测试工厂创建复杂测试数据
• setup-vitest5-migration - 有计划地迁移到 Vitest 5（5.0）

3. 模拟模式（高）

• mock-vi-mock-hoisting - 了解 vi.mock 的提升行为
• mock-spyon-vs-mock - 根据情况选择 vi.spyOn 或 vi.mock
• mock-implementation-not-value - 使用 mockImplementation 创建动态模拟
• mock-msw-network - 使用 MSW 模拟网络请求
• mock-avoid-overmocking - 避免过度模拟
• mock-type-safety - 确保模拟的类型安全
• mock-clear-between-tests - 清除测试之间的模拟状态（Vitest 5 中默认启用）

4. 性能（高）

• perf-pool-selection - 选择合适的性能池
• perf-disable-isolation - 在安全的情况下禁用测试隔离
• perf-happy-dom - 尽可能使用 happy-dom 而非 jsdom
• perf-sharding - 在 CI 中使用分片进行并行化
• perf-run-mode-ci - 在 CI 环境中使用运行模式
• perf-bail-fast-fail - 使用 bail 在 CI 中快速失败
• perf-bench-test-context - 使用 bench fixture 编写 Vitest 5 基准测试

5. 快照测试（中）

• snap-inline-over-file - 小型值优先使用内联快照
• snap-avoid-large - 避免大型快照
• snap-stable-serialization - 确保快照序列化稳定
• snap-review-updates - 提交前审查快照更新
• snap-describe-intent - 为快照测试取描述性名称

6. 环境（中）

• env-per-file-override - 必要时按文件覆盖环境
• env-setup-files - 使用设置文件进行全局配置
• env-globals-config - 统一配置全局变量
• env-browser-api-mocking - 模拟测试环境中不可用的浏览器 API

7. 断言（低至中）

• assert-specific-matchers - 优先使用特定匹配器，而非通用匹配器
• assert-edge-cases - 测试边界情况和边界值
• assert-one-assertion-concept - 每个测试只测试一个概念
• assert-expect-assertions - 在异步测试中使用 expect.assertions
• assert-toequal-vs-tobe - 正确选择 toBe 与 toEqual

8. 测试组织（低）

• org-file-colocation - 将测试文件与源文件放在一起
• org-describe-nesting - 使用 describe 块进行逻辑分组
• org-test-naming - 编写描述性测试名称
• org-test-skip-only - 适当地使用 skip 和 only

使用方法

先在项目根目录运行：

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

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

相关技能

• 有关 TDD 方法论，请参阅 tdd 技能
• 有关使用 MSW 进行 API 模拟，请参阅 msw 技能
• 有关 TypeScript 测试模式，请参阅 typescript 技能