测试编写指南（Testing Guidelines）
本指南说明在该代码库中编写测试时应遵循的原则。
一、用途 当新增功能、修复缺陷或需要测试时，可参照本指南编写测试。其目标是让测试验证行为而非实现细节，并在人工 QA 之前提供发布信心。
二、核心原则
- Mock 外部服务，使用真实夹具 始终 mock 第三方网络服务；始终使用基于真实数据的夹具。夹具必须清除 PII（使用 foo@example.com、user-123 这类假数据）。先捕获真实 API 响应，再进行脱敏。测试中绝不发起真实网络调用。
- 集成测试优先于单元测试 聚焦端到端风格的测试，验证输入与输出，而非实现细节。测试公共接口，而不是内部方法。单元测试对纯函数的边界情况有价值，但集成测试是优先项。如果重构破坏了测试但行为未变，说明测试与实现耦合过紧。
- 尽量减少边界用例测试 不要测试问题的每一种变体。彻底覆盖常见路径；跳过穷举式输入排列；跳过那些只增加维护负担而无价值的罕见边界情况。通常每类输入一个代表性测试即可。
- 缺陷必须补回归测试 发现缺陷时，始终添加一个本应捕获该缺陷的测试。该测试应在修复前失败、修复后通过，并用描述性命名记录该缺陷，以防止同一缺陷再次出现。注意：回归测试针对无意的损坏行为（缺陷），而非有意的变更。有意的功能移除、弃用或破坏性变更不需要回归测试——这些是设计决策，不是缺陷。
- 覆盖每一个用户入口点 每个客户/用户入口点至少有一个基本测试：CLI 命令、API 端点、公共/导出函数。先测常见/正常路径，以此证明入口点至少能工作。注意：“入口点”指公共接口——导出函数、CLI 命令、API 路由。内部/私有函数不是入口点，即使它们处理面向用户的标志或选项。测试入口点；内部函数通过这些测试获得覆盖。
- 测试先于人工 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
四、提交前检查清单
- 新入口点至少有正常路径测试
- 缺陷修复（非有意变更）包含回归测试
- 外部服务已 mock，并使用脱敏夹具
- 测试验证行为而非实现
- 测试之间没有共享状态
五、适用场景与限制 适用于采用 vitest 与 pnpm 的 TypeScript 代码库，尤其关注用户入口点与外部服务交互的测试。资料未说明其适用的具体编程语言、其他测试框架、CI 集成方式或收费情况，这些暂未提供。