Vitest测试最佳实践Skill vitest

name: vitest description: Vitest 测试框架的模式，用于测试设置、异步测试、使用 vi.* 进行模拟、快照和测试性能（原名为 test-vitest）。此技能应在编写或调试 Vitest 测试时使用。此技能不涵盖 TDD 方法论（使用 test-tdd 技能）、使用 MSW 进行 API 模拟（使用 test-msw 技能）或 Jest 特定 API。

Vitest 最佳实践

Vitest 测试框架的全面性能优化和最佳实践指南。包含 8 个类别中的 44 条规则，按影响优先级排序，以指导测试编写、重构和代码审查。

何时应用

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

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

按优先级的规则类别

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

快速参考

1. 异步模式（关键）

• async-await-assertions - 等待异步断言以防止误报
• async-return-promises - 从测试函数返回承诺
• 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 - 对复杂测试数据使用测试工厂

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 - 在测试间清除模拟状态

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 - 在 CI 中使用 bail 快速失败

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

如何使用

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

• 部分定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板
• async-await-assertions - 示例规则文件
• mock-vi-mock-hoisting - 示例规则文件

相关技能

• 对于 TDD 方法论，参见 test-tdd 技能
• 对于使用 MSW 进行 API 模拟，参见 test-msw 技能
• 对于 TypeScript 测试模式，参见 typescript 技能

完整编译文档

对于包含所有规则扩展的完整指南：AGENTS.md