ag-kit 测试模式实践指南:从测试金字塔到 Mock 策略的完整落地方案
ag-kit 测试模式实践指南:从测试金字塔到 Mock 策略的完整落地方案
本文以 ag-kit 仓库中 testing-patterns 技能文档 为核心骨架,系统讲解测试金字塔、AAA 模式、单元/集成测试原则、Mock 策略、测试组织与反模式规避等十大主题,并结合作品仓库中 CLI 测试套件 与 统一测试执行脚本 的真实实现进行源码级印证。读完本文,你将掌握一套可直接套用的"可靠测试套件"设计方法论——从如何分层选择测试类型,到如何组织测试数据、命名用例、规避反模式,并能在 Node.js(node:test)与 Python(pytest)等主流技术栈中立即落地。
1. 测试金字塔:用数量结构控制成本与速度
测试金字塔是整套测试策略的顶层架构。它的核心思想是:越靠近金字塔底部的测试越廉价、越快速、越稳定,因此数量应该越多;越靠近顶部的测试越昂贵、越脆弱,因此数量必须克制。
/\ E2E (Few)
/ \ Critical flows
/----\
/ \ Integration (Some)
/--------\ API, DB queries
/ \
/------------\ Unit (Many)
Functions, classes
三层测试的定位分别是:
- 单元测试(Unit,多):覆盖函数与类的行为,毫秒级执行,是日常开发反馈的主力;
- 集成测试(Integration,一些):覆盖 API、数据库查询等跨组件交互,验证接口契约;
- 端到端测试(E2E,少):只覆盖关键用户流程,速度慢、易受环境干扰,必须精挑细选。
这种"倒金字塔数量配比"不是拍脑袋:单元测试失败时定位成本最低(通常是单文件内),而 E2E 失败往往需要跨模块排查。把绝大多数验证下沉到单元层,是控制整个测试套件成本的最有效手段。
在 ag-kit 中,金字塔的三层结构都有对应落点:单元层覆盖 managed-tree.js 的纯逻辑函数;集成层通过临时目录 + 真实文件系统模拟完整的安装/更新/回滚流程;E2E 层则由 webapp-testing 技能 配套的 playwright_runner.py 对真实页面做冒烟测试。后面各节会逐一展开。
2. AAA 模式:每个测试的统一叙事结构
无论测试类型如何,每个测试都应遵循 Arrange–Act–Assert 三段式结构,让读者一眼看懂"准备什么、测什么、验证什么":
| Step | Purpose |
|---|---|
| Arrange | Set up test data |
| Act | Execute code under test |
| Assert | Verify outcome |
ag-kit 的 CLI 测试套件是 AAA 模式的教科书式范例。以 managed-tree.test.js 中的 "fresh install writes a managed-file manifest" 用例为例:
test("fresh install writes a managed-file manifest", async (t) => {
// Arrange:准备临时项目目录与"上游"待安装文件
const projectDir = await makeTempProject(t);
const incomingDir = path.join(projectDir, "incoming");
const currentDir = path.join(projectDir, ".agents");
await writeFiles(incomingDir, {
"agent/orchestrator.md": "orchestrator-v1",
"skills/example/SKILL.md": "skill-v1",
});
// Act:执行被测代码 installFreshTree
const report = await installFreshTree({
projectDir, incomingDir, currentDir,
toolkitVersion: "1.0.0", runId: "install-test",
});
// Assert:验证策略与清单结果
assert.equal(report.strategy, "install");
const manifest = await loadManifest(currentDir);
assert.equal(manifest.toolkitVersion, "1.0.0");
assert.deepEqual(Object.keys(manifest.files).sort(), [
"agent/orchestrator.md",
"skills/example/SKILL.md",
]);
});
注意两个细节:一是 Arrange 阶段通过 mkdtemp 在系统临时目录创建隔离环境,并用 t.after() 注册清理回调(Node 内置 test runner 的 hook),保证测试不污染开发机;二是断言使用 node:assert/strict 做严格相等比较。这种结构让"读测试 = 读需求"成为可能。
3. 测试类型选择:根据目标决定层级
不同类型的测试解决不同层级的问题,成本差异巨大,选型必须有的放矢:
| Type | Best For | Speed |
|---|---|---|
| Unit | Pure functions, logic | Fast (<100ms) |
| Integration | API, DB, services | Medium |
| E2E | Critical user flows | Slow |
具体到 ag-kit 的实践:
- 单元测试:
release-safety.test.js中对 "all GitHub Actions are pinned to immutable commit SHAs" 的校验(正则匹配uses: ...@<40位十六进制SHA>),就是纯逻辑函数的单元级验证; - 集成测试:
managed-tree.test.js的 "merge updates clean files, preserves local files, and reports true conflicts" 用例在真实临时文件系统上演练完整的三文件冲突场景,验证createUpdatePlan→applyUpdatePlan的完整调用链; - E2E 测试:Playwright 冒烟脚本对真实 URL 发起请求,检查页面标题、状态码、控制台错误与可访问性指标,属于"关键用户流程"级别。
4. 单元测试原则:快、隔离、可重复、自检、及时
优秀单元测试的五大标准
| Principle | Meaning |
|---|---|
| Fast | < 100ms each |
| Isolated | No external deps |
| Repeatable | Same result always |
| Self-checking | No manual verification |
| Timely | Written with code |
这五项标准本质上是"可持续性"的五个维度:测试太慢人们就不会频繁运行;依赖外部资源就会偶发失败;结果不确定就无法信任;需要人工核对就等于没有自动化;补写得太晚则失去回归价值。
该测什么、不该测什么
| Test | Don't Test |
|---|---|
| Business logic | Framework code |
| Edge cases | Third-party libs |
| Error handling | Simple getters |
判断边界的关键问题:这段逻辑崩溃会造成业务损失吗? 框架行为由框架作者负责,第三方库由它的上游测试保障,简单 getter 几乎没有行为可验证——把有限的测试预算投到真正承载业务规则的代码上。
ag-kit 用 node:test + node:assert/strict 实现零第三方依赖的单元测试(见 cli/package.json 的 "test": "node --test test/*.test.js"),全程不启动真实服务、不打真实网络,天然满足"Fast / Isolated / Repeatable"。其好处还体现在速度上:index.test.js 通过 npm bin 符号链接直接以 process.execPath 执行 CLI 并断言版本输出,整个套件毫秒级完成。
5. 集成测试原则:验证组件之间的契约
测什么
| Area | Focus |
|---|---|
| API endpoints | Request/response |
| Database | Queries, transactions |
| External services | Contracts |
集成测试的价值在于验证契约:请求能否到达端点、查询能否返回预期事务结果、外部服务的协议约定是否仍然成立。它不追求覆盖每个分支,而是保证组件间的"接缝"没有断裂。
Setup/Teardown 生命周期
| Phase | Action |
|---|---|
| Before All | Connect resources |
| Before Each | Reset state |
| After Each | Clean up |
| After All | Disconnect |
生命周期管理是集成测试可靠性的根基。ag-kit 的 managed-tree.test.js 用 Node 内置 test runner 的钩子实现了这套模式:makeTempProject(t) 在每个用例中创建临时目录(Before Each 的"重置状态"),t.after(async () => fse.remove(root)) 在用例结束后递归清理(After Each 的"清理")。由于每个用例拥有全新的文件系统快照,测试之间零状态泄漏,天然满足"独立测试、无顺序依赖"。
6. Mock 原则:只在隔离边界处造假
何时 Mock、何时不要
| Mock | Don't Mock |
|---|---|
| External APIs | The code under test |
| Database (unit) | Simple dependencies |
| Time/random | Pure functions |
| Network | In-memory stores |
Mock 的本质是在测试中替换掉不可控的依赖:外部 API 会变、数据库有状态、Date.now() 与随机数不稳定、网络可能抖动。但在单元测试中,被测代码本身、简单依赖和纯函数都不应被 Mock——纯函数输入输出确定,直接调用即可。
四种测试替身的选用
| Type | Use |
|---|---|
| Stub | Return fixed values |
| Spy | Track calls |
| Mock | Set expectations |
| Fake | Simplified implementation |
从源码结构看,ag-kit 的测试更多采用 Fake 与真实替身 策略而非过度 Mock:集成测试直接使用操作系统临时目录(os.tmpdir() + mkdtemp)作为真实文件系统的替身,用 fs-extra 真实读写;针对 manifest 中恶意路径(../../outside.txt)的校验用例(见 managed-tree.test.js)也完全基于真实文件系统断言 loadManifest 返回 null。这种"能真实就真实"的原则比无脑 Mock 更贴近生产行为。
7. 测试组织:命名即文档
命名模式
| Pattern | Example |
|---|---|
| Should behavior | "should return error when..." |
| When condition | "when user not found..." |
| Given-when-then | "given X, when Y, then Z" |
ag-kit 的测试命名采用了 "should + 行为" 模式,例如 managed-tree.test.js 中的 "fresh install writes a managed-file manifest"、"replace creates a backup that can be rolled back"。这些名字本身就是可读的需求描述——读到测试名就能推断被测能力。
分组结构
| Level | Use |
|---|---|
| describe | Group related tests |
| it/test | Individual case |
| beforeEach | Common setup |
Node node:test 提供了对应的分组能力:test() / describe() / it() 组织用例层级,beforeEach / afterEach / before / after 管理公共 setup。建议按被测模块(如 managed-tree、release-safety、CLI lifecycle)划分文件,文件内再按行为分组。
8. 测试数据:贴近真实、最小必要
三种生成策略
| Approach | Use |
|---|---|
| Factories | Generate test data |
| Fixtures | Predefined datasets |
| Builders | Fluent object creation |
- Factories:用函数批量生成带默认值的对象,适合大量相似数据;
- Fixtures:预定义好的一组静态数据集,适合"这组数据就该这样"的固定场景;
- Builders:链式 API 逐步装配对象,适合字段众多、可读性优先的场景。
数据四原则
- Use realistic data(用贴近真实的数据)
- Randomize non-essential values (faker)(随机化非关键字段)
- Share common fixtures(共享公共夹具)
- Keep data minimal(数据保持最小)
在 ag-kit 测试中,"最小化"体现得尤其明显:managed-tree.test.js 的 writeFiles 辅助函数接收 { relativePath: content } 映射,一次写入多组文件;index.test.js 用 t.after(() => rm(dir, { recursive: true, force: true })) 管理临时 bin 目录。数据都刻意保持极小——一个文件只含一行内容(如 "a-v1"、"keep me"),因为测试关注的是文件是否存在、内容是否被正确覆盖,而非内容的复杂结构。
9. 最佳实践:让测试套件长期可维护
| Practice | Why |
|---|---|
| One assert per test | Clear failure reason |
| Independent tests | No order dependency |
| Fast tests | Run frequently |
| Descriptive names | Self-documenting |
| Clean up | Avoid side effects |
其中"独立测试"与"清理副作用"在 ag-kit 的 release-safety.test.js 中体现为面向仓库整体的元测试:它读取真实的 package.json、package-lock.json、.agents/VERSION、GitHub Actions workflow 文件,断言版本在所有包与锁文件间保持一致、CI action 全部固定到 40 位 SHA、发布流程禁用 TLS 绕过并使用 Trusted Publishing 的 id-token: write。这类测试没有顺序依赖、不产生副作用,却把"发布安全"从人工检查清单变成了可重复执行的机器断言。
10. 反模式:从"不要做"的清单里学习
| ❌ Don't | ✅ Do |
|---|---|
| Test implementation | Test behavior |
| Duplicate test code | Use factories |
| Complex test setup | Simplify or split |
| Ignore flaky tests | Fix root cause |
| Skip cleanup | Reset state |
反模式清单是长期维护经验的浓缩:
- 测实现而非行为:测试一旦与内部实现细节耦合,重构时必然误报失败;应断言输入输出与对外契约;
- 重复测试代码:公共的临时目录创建、文件写入、生命周期清理应提炼为 helper(如
makeTempProject、writeFiles); - 复杂 setup:setup 比被测代码还复杂,说明测试划分粒度过粗,应拆分;
- 容忍 flaky 测试:偶发失败会系统性摧毁团队对测试的信任,必须追查根因(比如未隔离的共享状态、未清理的临时资源);
- 跳过清理:残留的临时目录、数据库记录会污染后续用例,是"顺序依赖"的头号来源。
ag-kit 的测试套件通过 t.after()、mkdtemp、独立临时目录等手段逐一规避了上述问题,并配套 release-safety.test.js 从 CI 与发布层面兜底。
11. 配套工具:ag-kit 的统一测试执行器
在 testing-patterns 技能目录 下,仓库还提供了配套的可执行脚本 test_runner.py,用于统一测试执行与覆盖率报告:
python test_runner.py <project_path> [--coverage]
该脚本会自动检测项目类型并选择框架:
- Node.js 项目:优先读
package.json的scripts.test(npm test);若安装了 vitest 则用npx vitest run --coverage,安装了 jest 则用npx jest --coverage; - Python 项目:检测到
pyproject.toml或requirements.txt时使用python -m pytest -v,覆盖率命令为python -m pytest --cov --cov-report=term-missing。
执行时它会解析输出中的 "X passed, Y failed" 模式统计用例数(兼容 Jest/Vitest 与 pytest 两种格式),设置 300 秒超时(防挂死),并输出 JSON 结构的结果摘要。从源码结构看,其设计意图是把"跑测试"统一成一条命令,无论底层是哪种框架,这正是测试金字塔"频繁运行快速测试"原则的工程化落地。
12. 与 TDD 工作流的衔接
testing-patterns 与仓库中的 tdd-workflow 技能 天然互补:TDD 定义 RED(先写失败测试)→ GREEN(最小实现通过)→ REFACTOR(保持绿色重构) 的开发节奏,而 testing-patterns 回答的是"每个阶段如何写出高质量的测试"。两者共享同一套 AAA 骨架与"一个测试只验证一个行为"的准则。推荐组合用法:
- 用 tdd-workflow 决定"先写什么测试"(happy path → 错误场景 → 边界 → 性能);
- 用 testing-patterns 决定"这个测试放哪层、要不要 Mock、数据怎么组织";
- 用
test_runner.py一键执行并获取通过率与覆盖率摘要。
结语:测试即文档
回到本技能文档的核心理念:"Tests are documentation. If someone can't understand what the code does from the tests, rewrite them."(测试就是文档,如果别人无法从测试理解代码在做什么,就重写它们。)
一条可执行的验收标准:当新成员加入项目时,让他先读测试而不是先读实现——如果他能仅凭测试名和断言重建出需求全貌,这套测试就是合格的。ag-kit 仓库(CLI 测试套件、release-safety 元测试、统一测试执行器)正是这一理念的完整参照实现,可直接作为搭建团队测试基础设施的样板。
延伸阅读:同仓库的相关文档还包括 TDD 工作流技能、Web 应用测试技能(含 Playwright 冒烟脚本),以及 qa-automation-engineer Agent 定义 与 test-engineer Agent 定义,可组合成一个完整的质量保障知识体系。