testing

测试技能

编写和运行测试的标准与工作流。每个功能都必须经过测试。

开始时声明：“我正在使用测试技能，以确保适当的测试覆盖。”

触发条件

• 为功能或缺陷修复编写新测试
• 添加新功能（必须包含测试）
• 修改已有测试覆盖的逻辑（必须更新测试）
• 在声称工作完成之前
• 在提交代码之前

框架

Vitest 4 — 在 vitest.config.ts 中配置。

测试结构

tests/
├── unit/          # Individual functions, utilities, components
├── integration/   # IPC, database, service interactions
├── regression/    # Regression test cases
└── e2e/           # End-to-end tests (Playwright, playwright.config.ts)

两种测试环境

环境	何时使用	文件命名
node（默认）	主进程、工具函数、服务	*.test.ts
jsdom	依赖 DOM/浏览器的代码	*.dom.test.ts

工作流

步骤 1：确定要测试的内容

在编写测试之前，先列出风险最高的场景：

• 当依赖返回 undefined / 抛出异常时会发生什么？
• 在边界条件下会发生什么（空列表、最大重试次数、过去的时间戳）？
• 生产环境中最可能出问题的地方是什么？

步骤 2：编写测试

遵循以下质量规则：

1. 描述行为，而不是代码结构

// Wrong — describes implementation
it('should call repo.getConversation', ...)

// Correct — describes behavior
it('should return cached task without hitting repo on second call', ...)
it('should reject with error when conversation does not exist', ...)

2. 每个 describe 块必须至少覆盖一条失败路径

只测试正常路径会让最危险的代码缺乏测试。

3. 每个测试只验证一个行为

让每个 it() 保持聚焦。一个测试中超过 3 个 expect() 调用，说明它一次测试了太多内容。

4. 自检

写完一个测试后，在脑中删除它针对的核心逻辑。如果测试仍然通过，就重写它 — 它没有守护任何东西。

5. 从风险出发，而不是从覆盖率缺口出发

列出最可能产生缺陷的场景。先写这些测试。覆盖率是结果，而不是起点。

步骤 3：运行测试

bun run test              # Run all tests (REQUIRED before every commit)
bun run test:coverage     # Check coverage (before opening a PR)

步骤 4：验证覆盖率

覆盖率目标：对于 vitest.config.ts → coverage.include 匹配的所有源文件，覆盖率 ≥ 80%（当前为 src/**/*.{ts,tsx} 以及少量脚本）。

新的源文件会自动纳入覆盖率 — 无需手动修改配置。如果新文件被 coverage.exclude 中的规则意外排除，请将其从排除列表中移除。

步骤 5：更新已有测试

修改逻辑时，检查已有测试是否需要更新：

bun run test -- --reporter=verbose   # See which tests pass/fail with names

如果测试因行为被有意更改而失败，请更新测试。如果测试意外失败，请调查原因。

边界情况检查清单

测试模块时，请验证：

• 已处理 null / undefined 输入
• 已处理空数组/空对象
• 已处理依赖抛出的错误
• 边界值（0、-1、最大值、空字符串）
• 异步操作（超时、拒绝、取消）

快速检查清单

提交代码之前：

• 新功能有对应的测试用例
• 修改的逻辑有更新的测试
• bun run test 通过
• 测试描述的是行为，而不是实现
• 每个 describe 块至少有一条失败路径
• 新的源文件没有被 coverage.exclude 意外排除
• bun run test:coverage 达到 ≥ 80% 目标

常见错误

错误	正确做法
测试实现细节	测试可观察的行为
只测试正常路径	必须至少包含一条失败路径
一个 it() 中有 5 个以上 expects	拆分为多个测试
跳过“简单”代码的测试	简单代码也会出错 — 测试有风险的部分
在说“完成”之后才写测试	测试是“完成”的一部分，而不是事后补充