testing-best-practices

测试最佳实践

单元测试、集成测试和 TDD 原则，助力构建可靠、易维护的测试套件。包含 7 个类别中的 34 条规则，使用 TypeScript 和 Jest/Vitest。

元数据

• 版本： 2.0.0
• 规则数量： 7 个类别中的 34 条规则
• 许可证： MIT

适用场景

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

• 编写单元测试或集成测试
• 审查测试代码质量
• 改进测试覆盖率策略
• 搭建测试基础设施
• 调试不稳定或运行缓慢的测试

按优先级划分的规则类别

优先级	类别	影响	前缀
1	测试结构	严重	struct-
2	测试隔离	严重	iso-
3	断言	高	assert-
4	测试数据	高	data-
5	Mock	中	mock-
6	覆盖率	中	cov-
7	性能	低	perf-

快速参考

1. 测试结构（严重）

• struct-aaa-pattern - Arrange、Act、Assert 模式
• struct-descriptive-names - 使用描述性测试名称
• struct-one-assertion - 每个测试只包含一个逻辑断言
• struct-describe-it - 使用 describe/it 组织测试套件
• struct-given-when-then - 适当时采用 BDD 风格
• struct-setup-teardown - 正确设置和清理

2. 测试隔离（严重）

• iso-independent-tests - 测试独立运行
• iso-no-shared-state - 不共享可变状态
• iso-deterministic - 每次运行结果相同
• iso-no-order-dependency - 可按任意顺序运行
• iso-cleanup - 测试后进行清理
• iso-test-doubles - 有策略地使用测试替身

3. 断言（高）

• assert-specific - 使用具体的断言
• assert-meaningful-messages - 提供有用的失败消息
• assert-expected-actual - 先写预期值
• assert-no-magic-numbers - 使用命名常量
• assert-custom-matchers - 为领域逻辑创建自定义匹配器

4. 测试数据（高）

• data-factories - 使用工厂生成测试数据
• data-builders - 对复杂对象使用建造者模式
• data-faker - 生成逼真的假数据
• data-minimal - 使用最少量的测试数据
• data-realistic - 覆盖逼真的边界情况
• data-fixtures - 管理测试固定数据

5. Mock（中）

• mock-boundaries - 只在边界处使用 Mock
• mock-verify-interactions - 验证重要的 Mock 调用
• mock-minimal - 不要过度使用 Mock
• mock-realistic - 使用 MSW 模拟逼真的行为

6. 覆盖率（中）

• cov-meaningful - 关注有意义的覆盖率
• cov-edge-cases - 覆盖边界情况和边界值
• cov-unhappy-paths - 测试错误场景
• cov-not-100-percent - 100% 覆盖率并非目标

7. 性能（低）

• perf-fast-unit - 保持单元测试快速（每个测试 <50ms）
• perf-parallel - 并行运行测试
• perf-test-organization - 组织测试以便快速获得反馈

核心指南

AAA 模式（Arrange、Act、Assert）

it('calculates total with discount', () => {
  // Arrange
  const cart = new ShoppingCart();
  cart.addItem({ name: 'Book', price: 20 });
  cart.applyDiscount(0.1);

  // Act
  const total = cart.getTotal();

  // Assert
  expect(total).toBe(18);
});

描述性测试名称

// ✅ Describes behavior and scenario
describe('UserService.register', () => {
  it('creates user with hashed password', () => {});
  it('throws ValidationError when email is invalid', () => {});
  it('sends welcome email after successful registration', () => {});
});

测试隔离

// ✅ Each test sets up its own data
beforeEach(() => {
  mockRepository = { save: vi.fn(), find: vi.fn() };
  service = new OrderService(mockRepository);
});

使用方法

阅读各规则文件，了解详细说明：

rules/struct-aaa-pattern.md
rules/iso-independent-tests.md
rules/mock-boundaries.md
rules/cov-meaningful.md

参考资料

• Vitest 文档
• Jest 文档
• Testing Library
• MSW（Mock Service Worker）

完整汇编文档

如需查看包含所有规则详细内容的完整指南：AGENTS.md