vitest-best-practices

Vitest 最佳实践

何时应用此技能

遇到以下任一情形时，请使用此技能：

文件模式

• 处理 *.test.ts、*.spec.ts 或类似测试文件
• 为 TypeScript/JavaScript 模块创建新的测试文件
• 审查现有的 vitest 测试套件

用户意图关键词

• 用户提到：vitest、测试、TDD、BDD、单元测试、集成测试
• 用户要求：编写测试、增加测试覆盖率、修复失败的测试、重构测试
• 用户讨论：模拟、桩、断言、测试性能、测试组织

代码上下文

• 从 vitest 导入内容的文件（describe、it、expect、vi）
• 测试设置/清理代码（beforeEach、afterEach、beforeAll、afterAll）
• 使用 vi.mock()、vi.spyOn()、vi.fn() 实现的模拟/间谍
• 断言链（expect(...).toEqual()、.toBe()、.toThrow() 等）

常见任务

• 为现有功能编写新的测试用例
• 重构测试，以提升清晰度或性能
• 调试不稳定或失败的测试
• 提升测试覆盖率或可维护性
• 审查测试代码是否符合最佳实践

不要在以下情形使用此技能

• 使用 Playwright/Cypress 编写端到端测试（范围不同）
• 任务纯粹涉及实现代码，而非测试

此技能涵盖的内容

此技能全面介绍以下内容：

1. 测试组织：文件放置位置、命名约定、分组策略
2. AAA 模式：使用 Arrange、Act、Assert 结构提升清晰度
3. 参数化测试：使用 it.each() 测试不同情况
4. 错误处理：测试异常、边界情况和故障注入
5. 断言：选择严格断言（toEqual、toStrictEqual、toThrow）
6. 测试替身：Fake、桩、模拟、间谍——何时使用各自的方式
7. 异步测试：Promise、async/await、定时器和并发测试
8. 性能：快速测试、避免开销大的操作、清理模式
9. Vitest 专属功能：覆盖率、监视模式、基准测试、类型测试、设置文件
10. 快照测试：何时以及如何有效使用快照

使用方法

此技能采用渐进式披露结构，以尽量减少上下文用量：

1. 从概览开始（AGENTS.md）

阅读 AGENTS.md，简要了解所有规则及其单行摘要。

2. 按需加载具体规则

确定相关优化后，加载对应的参考文件，了解详细的实现指南：

核心模式：

• organization.md
• aaa-pattern.md
• parameterized-tests.md
• error-handling.md
• assertions.md
• test-doubles.md

进阶主题：

• async-testing.md
• performance.md
• vitest-features.md
• snapshot-testing.md

3. 应用模式

每个参考文件都包含：

• ❌ 展示反模式的错误示例
• ✅ 展示最佳实现方式的正确示例
• 关于此模式为何重要的说明

快速示例

此技能可帮助你将不清晰的测试改写为清晰、易维护的测试：

之前（不清晰）：

test('product test', () => {
  const p = new ProductService().add({name: 'Widget'});
  expect(p.status).toBe('pendingApproval');
});

之后（使用此技能优化）：

describe('ProductService', () => {
  describe('Add new product', () => {
    it('should have status "pending approval" when no price is specified', () => {
      // Arrange
      const productService = new ProductService();

      // Act
      const newProduct = productService.add({name: 'Widget'});

      // Assert
      expect(newProduct.status).toEqual('pendingApproval');
    });
  });
});

核心原则

• 清晰胜于巧妙：测试应当一目了然
• 结构扁平：避免在 describe 块中深层嵌套
• 每个概念一个断言：让测试聚焦于单一行为
• 严格断言：优先使用 toEqual 而非 toBe，必要时使用 toStrictEqual
• 尽量少用模拟：条件允许时使用真实实现
• 快速执行：通过高效的设置/清理让测试保持快速