testing-guidelines

测试指南

编写此代码库的测试时，请遵循以下原则。

核心原则

1. 模拟外部服务，使用真实数据样例

始终模拟第三方网络服务。始终使用基于真实数据的样例。

• 样例必须去除 PII（使用 [email protected]、user-123 等虚拟数据）
• 捕获真实 API 响应，然后对其进行清理
• 测试中绝不进行实际网络调用

2. 优先编写集成测试，而非单元测试

重点编写端到端风格的测试，验证输入和输出，而非实现细节。

• 测试公共接口，而非内部方法
• 单元测试适用于纯函数的边缘情况，但应优先编写集成测试
• 如果重构导致测试失败，但行为没有变化，说明这些测试与实现耦合过紧

3. 尽量减少边缘情况测试

不要测试问题的每一种变体。

• 全面覆盖常见路径
• 跳过穷举式的输入排列组合
• 跳过那些不太可能发生、却增加维护负担而没有价值的边缘情况
• 通常每类输入各测试一个有代表性的情况就足够了

4. 始终为 Bug 添加回归测试

发现 Bug 时，始终添加一个本可以捕获该 Bug 的测试。

• 修复前测试应失败，修复后应通过
• 使用描述性名称，以记录该 Bug
• 这样可以防止同一个 Bug 再次出现

**注意：**回归测试针对的是意外的行为损坏（Bug），而非有意的变更。有意移除功能、弃用功能或进行不兼容变更时，无需添加回归测试——这些是设计决策，而非缺陷。

5. 覆盖每个用户入口点

始终为每个客户／用户入口点至少编写一个基本测试。

• CLI 命令、API 端点、公共／导出函数
• 首先测试常见／正常路径
• 这可以证明入口点确实有效

注意：“入口点”指公共接口——导出函数、CLI 命令、API 路由。内部／私有函数不是入口点，即使它们处理面向用户的标志或选项。测试入口点；内部函数通过这些测试获得覆盖。

6. 测试应先于手动 QA 验证功能

手动测试之前，我们通过测试验证任何功能是否正常工作。

• 先编写测试或与代码同步编写，不要事后补写
• 如果无法测试，请重新考虑设计
• 测试通过后，应让人有信心发布

技术指南

文件组织

• 测试文件使用 *.test.ts 扩展名
• 测试文件与源文件放在一起：foo.ts → foo.test.ts

测试隔离

每个测试都必须：

• 独立运行，且不影响其他测试
• 文件操作使用临时目录
• 在 afterEach 钩子中清理资源

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

describe('my feature', () => {
  let tempDir: string;

  beforeEach(() => {
    tempDir = join(tmpdir(), `warden-test-${Date.now()}`);
    mkdirSync(tempDir, { recursive: true });
  });

  afterEach(() => {
    rmSync(tempDir, { recursive: true, force: true });
  });

  it('does something with files', () => {
    writeFileSync(join(tempDir, 'test.ts'), 'content');
    // ... test code
  });
});

纯函数测试

对于没有副作用的纯函数，无需特殊设置：

import { describe, it, expect } from 'vitest';
import { matchGlob } from './matcher.js';

describe('matchGlob', () => {
  it('matches exact paths', () => {
    expect(matchGlob('src/index.ts', 'src/index.ts')).toBe(true);
  });
});

运行测试

pnpm test              # Run all tests in watch mode
pnpm test:run          # Run all tests once

提交前检查清单

• 新增入口点至少有一个正常路径测试
• Bug 修复（非有意变更）包含回归测试
• 外部服务使用已清理的样例进行模拟
• 测试验证行为，而非实现
• 测试之间没有共享状态