"测试通过"和"功能真的能用"之间隔着好几层容易被忽略的陷阱——mock 太多会验证不到真实链路,覆盖率只证明代码跑过、不证明行为正确,而 CI 矩阵如果全靠 YAML 手写会迅速失控成没人敢改的黑箱。DeepSeek Harness 用一套分层的 Vitest 测试体系 + 一套用 TypeScript 编写的门禁编排器(
scripts/run-gates.ts)来同时压住这几个问题,本篇逐层拆开这套体系,并用docs/testing.md里的原文措辞讲清楚背后的测试哲学。
(课程写作时docs/testing.md的 Tiers 一节列的是五层,现在实测已经变成七层——新增了 "Owner-local expected output" 和 "Performance benchmarks" 两层,本文已按当前实际内容更新;这类"层数/门禁数量"的具体断言建议读者去仓库里cat docs/testing.md核对一遍最新版本,不要死记本文的数字。)
学习目标
- 理解 Vitest 分层测试(unit / coverage / e2e / expected / bench / snapshot / web,共七层)各自验证什么、为什么不能合并成一层。
- 能引用
docs/testing.md里几条核心测试哲学的准确措辞,并理解它们各自对应的具体工程手段(而不是空洞的口号)。 - 理解 GitHub Actions
ci.yml里all-checks-passed汇总门禁背后 required jobs 的设计意图,以及为什么要用scripts/run-gates.ts而不是纯 YAML 去编排具体检查项。 - 理解 lefthook 本地 hook 和 CI 完整矩阵之间"快反馈 vs 全覆盖"的分工关系。
- 知道
.gitlab-ci.yml在这套体系里承担的专门角色,以及它为什么和 GitHub Actions 分离。
背景与设计动机
如果只跑一层"能过就行"的单元测试,会掉进什么坑?最典型的是"绿色的单测,坏掉的产品"——一个组件的所有子函数都被 mock 到位、单测全绿,但真实的组装路径(Loader 装配、进程间协议、构建产物的模块解析)从来没有被跑过一次,直到用户手上才炸。反过来,如果每次提交都跑一遍真实调用 LLM API 的端到端测试,本地开发和无密钥的贡献者会被彻底挡在门外。这两个极端都不可接受,所以测试必须分层,每一层验证不同的"真实性"维度,而不是简单地叠加更多断言。
CI 编排同样面临一个类似的取舍:全部写成 GitHub Actions YAML 的 run 步骤,意味着"这次到底跑了哪些检查、依赖关系是什么、并发度怎么控制"这些逻辑分散在几十个 job 里,改一次门禁要在 YAML 里到处改脏活。DeepSeek Harness 把"检查项的依赖图、并发调度、失败汇总"这部分逻辑写成了一个真正的 TypeScript 程序(scripts/run-gates.ts),YAML 里的每个 job 只负责调用这个程序的某个具名模式(ci-static、ci-coverage 等),把"编排"这件事从声明式配置降级成了普通的程序设计问题——可以写类型、可以写测试、可以本地直接跑。
核心机制详解
Vitest 七层测试体系
docs/testing.md 用"Tiers"一节把测试体系拆成七层(课程写作时是五层,新增了 expected 和 bench 两层),每层对应一个独立的 vitest config 文件:
1# docs/testing.md(当前版本节选,已按新增的两层做了删减聚焦) 2- **Unit** (`pnpm run test`): vitest over package and example specs under their 3 `tests/**` directories plus repository script specs under `scripts/**/*.spec.ts`; 4 tests stay with the code area they exercise. Every registry gets an HMR-safety 5 test (dispose the contributing fiber, assert cleanup). 6- **Coverage gate** (`pnpm run test:coverage`): the gating run, per-file 100% on 7 `packages/*/*/src`. An uncovered line is often dead code the gate flags for 8 deletion, not a missing test to bolt on. 9- **Real-API e2e** (`pnpm run test:e2e`): with-key tests against live provider 10 APIs — the DeepSeek model plus provider-specific smokes that gate on their own 11 keys (`EXA_API_KEY`, `PERPLEXITY_API_KEY`, …); each suite self-skips without 12 its key so keyless CI stays green. 13- **Owner-local expected output** (`pnpm run test:expected`)(新增): keyless 14 assembled CLI/process expectations without a recorded-session round trip. 15 Drivers use `*.expected.e2e.ts` beside `tests/expected/`; CI runs built exports. 16- **Performance benchmarks** (`pnpm run test:bench`; required Linux PR gate 17 `node 24 / benchmarks`)(新增): `benchmarks/` groups user-path gates. It 18 builds libraries and workers; timed code runs under plain Node, never TSX. 19 Synthetic inputs enforce time, heap, and scaling budgets. 20- **Snapshot** (`pnpm run test:snapshot`): a top-level scenario's highest 21 recorded parent generation supplies user input and model replay, then serves 22 as the expected persisted result. Process scenarios start through `dsh`: 23 headless owns one-shot behavior, the SDK owns persistent control, ACP owns 24 automation-protocol behavior, and Web retains browser/ARIA evidence. 25- **Web browser snapshot** (`pnpm run test:web`; required Linux PR gate): 26 Chromium compares session-driven output under `snapshots/web/` and UI-only 27 output under `apps/web/tests/expected/`. CI forces read-only 28 `DSH_SNAPSHOT=replay`, never writing expected outputs.
对应关系是 vitest.config.ts(unit + coverage 共用同一份配置,只是 coverage 多传 --coverage)、vitest.e2e.config.ts(real-API)、vitest.expected.config.ts(owner-local expected output,新增)、vitest.bench.config.ts(performance benchmarks,新增,对应新的顶层 benchmarks/ workspace 成员)、vitest.snapshot.config.ts(keyless 快照)、vitest.web.config.ts(浏览器快照)。新增的两层里,expected 解决的是"snapshot 需要录制模型回放、成本较高"和"e2e 需要真实 API key"之间的中间地带——不需要密钥也不需要录制会话,直接断言构建产物 CLI/进程的确定性输出;bench 则是把性能预算(耗时、堆内存、随规模变化的增长曲线)第一次变成了正式的、会挡 PR 的 CI 门禁,而不只是包内自查的诊断脚本(.perf.ts)。每一层解决的是不同问题:
- Unit 关心的是代码区域自身的正确性——放在被测代码旁边的
tests/**目录里,而不是集中式的顶层测试目录。仓库要求"每个 registry 都要有 HMR 安全性测试":卸载贡献插件的 fiber,断言清理逻辑正确执行——这直接对应 Cordis 插件系统的热重载语义。 - Coverage gate 是真正卡 CI 的门禁,要求
packages/*/*/src下逐文件 100% 行覆盖率。vitest.config.ts里能看到这个阈值配置是硬编码的:
1// vitest.config.ts(当前版本;阈值现在包在一个 coveragePartitionMode 判断里, 2// 因为覆盖率门禁现在支持拆分成多个并发分区跑,分区模式下不需要在每个分区里 3// 单独判定 100% 阈值,汇总阶段才做最终判定) 4coverage: { 5 provider: 'v8', 6 include: ['packages/*/*/src/**/*.{ts,tsx}'], 7 exclude: [ 8 'packages/*/*/src/types.ts', 9 'packages/*/*/src/bin.ts', 10 'packages/*/*/src/worker.ts', 11 // ... 12 ], 13 // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome). 14 // Per-file so a well-covered big file can't subsidize a bare one. 15 thresholds: coveragePartitionMode 16 ? undefined 17 : { 18 perFile: true, 19 statements: 100, 20 branches: 100, 21 functions: 100, 22 lines: 100, 23 }, 24}, 25
perFile: true 是关键设计——它防止"一个测得很充分的大文件"把"一个几乎没测的小文件"的平均分拉上去。豁免机制也是显式且有记录的,比如 pwsh-local 相关文件的覆盖率豁免直接写在配置里,并附带探测逻辑:
1// vitest.config.ts 2// pwsh-local's run/start/lifecycle suites self-skip without a real pwsh 3// (executor.spec.ts hasPwsh), leaving this file far below per-file 100% 4// on pwsh-less hosts; the exemption keeps those hosts green while CI 5// runners ship pwsh and still enforce the full bar. 6const pwshCoverageExclusions = spawnSync(resolvePwshPath(), [...]).status === 0 7 ? [] 8 : ['packages/shell/pwsh-local/src/index.ts', 'packages/shell/pwsh-sandbox/src/**/*.ts'] 9
这条豁免不是"我们懒得测",而是显式声明"这个文件的覆盖率依赖一个本地环境不一定具备的外部程序(真实的 pwsh),豁免只在探测不到 pwsh 时生效,CI 跑在真装了 pwsh 的 runner 上时依然强制满覆盖率"。
- Real-API e2e 是"是否真的能用"的最后一道防线。
vitest.e2e.config.ts里能看到测试超时被放宽到 120 秒、重试 2 次:
1// vitest.e2e.config.ts 2test: { 3 ... 4 // Real model calls: generous timeouts, and retries for transient flakes 5 // (the shared internal key hits concurrency quotas). No coverage — the 6 // unit suites own the coverage gate. 7 testTimeout: 120_000, 8 hookTimeout: 30_000, 9 retry: 2, 10 fileParallelism: e2eMaxWorkers > 1, 11 maxWorkers: e2eMaxWorkers, 12}, 13
- Snapshot 和 Web browser snapshot 分别验证"协议/展示层的外部行为"和"浏览器渲染出来的真实像素/DOM"。
test:web在 CI 里被固定成只读回放模式(DSH_SNAPSHOT=replay),永不在 CI 里写期望输出——录制和刷新只能在本地做,每一次 diff 都要求人工审查。
几条测试哲学,以及它们对应的具体机制
docs/testing.md 里的措辞相当克制,但每一句背后都指向仓库里可以验证的具体机制,不是空洞的原则宣言。
"We are DeepSeek — do not ration real-API tests." 完整上下文是:
A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Cover file-writing prompts, multi-turn conversations, tool use, and mid-stream cancellation. Highest-value are smoke tests that boot the real example, send one prompt, and check the world — they catch the "green unit tests, broken product" class that mocks cannot (postmortem 0001).
这句话背后有一个真实的踩坑记录——docs/postmortem/0001-acp-default-export-drops-inject.md——说明这条原则不是理论推导,而是从一次真实事故里总结出来的。
"Prefer the real implementation over a mock." 原文强调只在"昂贵或不确定"的边界上打 mock,举例用的具体测试工具函数在课程写作之后换过一次,但原则完全没变:
Mock only the expensive or non-deterministic boundary (LLM adapter, network, clock); keep everything downstream real. A hand-rolled stand-in proves the bridge moves bytes, not that the shipping tool behaves as asserted. Bridge tool-call tests keep the real tool registry and pipeline behind the scripted mock model:
makeBridgeHarness()mounts the loop, session store, tool registry, and JSONL persistence with aMockAdapteras the only mock (packages/acp/acp/tests/harness.ts).
也就是说测试里唯一被替身的是"模型会返回什么 token"这个不确定的边界(MockAdapter),循环本身、会话存储、工具注册表、JSONL 持久化全都是真实代码路径。
"Verify the world, not the self-report." 这条直接约束断言的写法:
An e2e assertion re-runs the command or re-reads the file externally; a keyword probe on the agent's own output lets a cheating agent pass. Assert untouched files are byte-identical.
意思是不要去检查"agent 自己说它写完了文件",而要真的重新读一次那个文件、重新跑一次那个命令去验证——这条规则专门用来防止"模型输出里恰好带对了关键词,但实际什么都没做"这种假阳性。
"Test the real entry path." 这条把"真实"细化到了"发布出去的那份构建产物本身":
"Real entry path" means the published artifact: a package
binruns builtlib/bin.jsunder plainnode, exposing failures tsx masks (settle races, module resolution, swallowed load failures). ... Keep the built-artifact smokes green (packages/examples/*/tests/built-bin.e2e.ts,packages/ptc-runtime/ptc-runtime-node/tests/built-lib.e2e.ts), and assert a genuinely-missing config exits non-zero.
这段引用本身有一处值得留意的细节:docs/testing.md 原文举的例子里仍然写着 packages/examples/*/tests/built-bin.e2e.ts,但 packages/examples 这个分类目录在第 01 篇讲到的那次重构里已经被移除了——实测这个测试现在的真实路径是 apps/cli/tests/built-bin.e2e.ts。这说明连仓库自己的文档在快速迭代下也会出现"代码已经挪了、文档里的例子还没跟上"的滞后,是个提醒:读到具体路径类的例子时,养成用 find/grep 核实一遍的习惯,比死记文档原文更可靠。
apps/cli/tests/built-bin.e2e.ts、packages/ptc-runtime/ptc-runtime-node/tests/built-lib.e2e.ts 这类测试专门跑构建产物而不是源码——因为 tsx 直接跑 .ts 源码时,某些只在真实模块解析、真实 worker/子进程边界才会出现的问题会被悄悄掩盖掉。这类"跑构建产物"的 built-lib.e2e.ts 测试现在分布得更广了,packages/experimental/*(webworker-packer、inspector、agent-team)、packages/lsp/lsp-stdio、packages/api/remotes 下都能找到同名文件——不再局限于课程写作时点名的那一两个包,是这条测试原则被更广泛套用的结果(此处 packages/examples 分类目录、code-runtime 分类目录都已经不存在了,参考第 01 篇)。
GitHub Actions:required jobs 与 all-checks-passed
.github/workflows/ci.yml 现在有 720 行左右(课程写作时是 900 多行——行数变少不代表检查变少,而是自托管 runner 的失败转移逻辑被重构、注释也更集中了),最终的汇总门禁逻辑依然很简单——all-checks-passed 这一个 job 声明了 PR 真正必须全绿的 job 清单,但清单本身变长了:
1# .github/workflows/ci.yml(当前版本) 2all-checks-passed: 3 name: all checks passed 4 # This bookkeeping-only verdict must not depend on custom-pool 5 # provisioning — and under Linux failover it follows the same selector as 6 # the worker jobs it aggregates, so a standard-hosted outage cannot strand 7 # the branch-protection verdict either. ... 8 needs: [node-24, node-24-coverage, node-24-bench, node-24-consumers, node-compat, python-sdk, python-runtime, windows-build, windows-native-tests] 9 steps: 10 - name: Fail if any needed job did not succeed 11 if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') 12 ... 13 - name: All checks passed
和课程写作时相比,needs 列表有两处变化:新增了 node-24-bench(对应上一节新增的 Performance benchmarks 门禁层),原来的单个 windows job 拆成了 windows-build 和 windows-native-tests 两个独立 required job(另有一个不在 required 列表里的观察窗 windows-coverage,跑 PR 但不参与合并判定)。其余维度含义不变:node-24("node 24 / static",静态检查)、node-24-coverage("node 24 / coverage",覆盖率门禁)、node-24-consumers("node 24 / snapshots and artifacts",快照 + 构建产物验证 + Playwright 浏览器快照)、node-compat(Node 双矩阵兼容性)、python-sdk(无密钥 SDK 套件)、python-runtime(单文件可执行体的发布形态 smoke)。job 内的新注释还透露了一个课程写作时没有的细节:CI 现在有一套显式的"自托管失败转移"开关(DSH_CI_FAILOVER_LINUX),all-checks-passed 这个纯汇总 job 也要跟着同一个开关重新定位到备用 runner 池(vm-backup/blacksmith),避免自托管池故障时连"这个 PR 到底算不算全绿"这个判断本身都卡住。其余像 ci-master.yml 里的 windows(Wine 演练,原称 windows-native)、serial-linux-selfhosted、serial-macos、serial-windows 这些 job 依然是自愈演练,不在 required 列表里——它们在每次 master push 上重复验证自托管失败转移池的可用性,不参与 PR 是否可合并的判断。
scripts/run-gates.ts:用程序而不是 YAML 编排门禁
每个 CI job 的具体检查内容不是写在 YAML 里,而是通过一个统一的 CLI 委托给 scripts/run-gates.ts:
1// scripts/run-gates.ts 2export type Mode = 3 | 'ci-primary' 4 | 'ci-linux-primary' 5 | 'ci-static' 6 | 'ci-lint-contracts-ready' 7 | 'ci-coverage' 8 | 'ci-bench' 9 | 'ci-snapshot' 10 | 'ci-artifacts' 11 | 'ci-consumers' 12 | 'ci-windows-blocking' 13 | 'ci-windows-complete' 14 | 'ci-windows-observational-ready' 15 | 'node-compat' 16 | 'check-all' 17 | 'hygiene' 18 | 'doc-sync' 19 | 'doc-quick' 20 21export function gatesForMode(selected: Mode): Gate[] { 22 switch (selected) { 23 case 'ci-primary': 24 return ciPrimaryGates() 25 case 'ci-static': 26 return ciStaticGates({ ownsBuild: false }) 27 case 'ci-coverage': 28 return coverageGates() 29 // ... 30 } 31} 32
ci-static 模式展开后是一组具体的检查项组合:
1// scripts/run-gates.ts 2function ciStaticGates(options: { ownsBuild: boolean }): Gate[] { 3 return [ 4 ...ciSharedStaticGates(), 5 ...options.ownsBuild ? [pnpmScript('build', 'build')] : [], 6 ...docSyncLeafGates({ /* ... */ }), 7 pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }), 8 pnpmScript('knip', 'knip'), 9 ] 10} 11
每个 Gate 是一个带 id、command、needs(依赖的其他 gate)、allowFailure 的普通对象,调度器 runGates() 用这份依赖图做有界并发调度(DSH_GATE_CONCURRENCY 环境变量可覆盖并发度)。这样设计的好处是显而易见的:门禁的依赖关系、并发策略、失败汇总逻辑全部是可以本地单独运行、单独调试、写单测覆盖的 TypeScript 代码,而不是散落在 YAML run: 步骤里的 shell 片段拼接。改一次"覆盖率门禁应该在哪些检查之后跑"只需要改 needs 数组,不需要理解 GitHub Actions 的 needs:/矩阵语法怎么和自定义 shell 脚本纠缠在一起。
lefthook:本地快反馈,CI 全覆盖
lefthook.yml 开头的注释直接说明了分工原则:
1# lefthook.yml 2# Git hooks (lefthook). Keep these local checkpoints fast; CI owns the full 3# repository-wide gate matrix. 4# Install: `node scripts/install-lefthook.mjs` (runs automatically via postinstall).
pre-commit 只做与本次改动直接相关、能在几秒内跑完的检查——翻译配对校验(仅校验 staged 的 *.i18n.yaml)、archived agent notes 格式、对 staged 文件跑 oxlint 自动修复、第三方 notice 自动重生成、空白检查、vendor manifest 一致性守卫:
1# lefthook.yml 2pre-commit: 3 jobs: 4 - name: lint (staged) 5 glob: '*.{ts,tsx,mts,cts,mjs}' 6 exclude: ['vendor/*/src/**'] 7 run: node_modules/.bin/tsx scripts/run-oxlint.ts --config .oxlintrc.staged.json --fix --no-error-on-unmatched-pattern {staged_files} 8 stage_fixed: true 9 - name: vendor manifest guard 10 run: scripts/check-vendor-manifest.sh
pre-push 则只跑一项——完整的 pnpm run typecheck,这是本地能负担、又能拦住"类型错误才推上去被 CI 打回来"这种最常见浪费的最后一道防线。真正的"全仓库 100% 覆盖率""Windows Wine 矩阵""Playwright 浏览器快照"这些开销大、跑得慢的检查,全部只在 CI 里跑——本地 hook 从不试图复制它们。
.gitlab-ci.yml:专职 Python wheel 发布
仓库同时维护一份 .gitlab-ci.yml,和 GitHub Actions 的职责完全不重叠——它只在打 python-v* 格式的 tag 时触发,分 build/publish 两个 stage,产出并发布 Python SDK 的 wheel 包(SDK wheel + 五个平台的 runtime wheel:linux x64/arm64、macOS arm64/x64、windows x64——课程写作时还只有三个平台):
1# .gitlab-ci.yml 2workflow: 3 rules: 4 - if: '$CI_COMMIT_TAG =~ /^python-v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$/' 5 - when: never 6 7stages: 8 - build 9 - publish
它验证 tag 版本号与 package.json 一致,构建单文件可执行体,用 smoke-python-runtime.py 做发布形态的 smoke 测试,最后用 twine upload 发布——这条流水线和 GitHub Actions 的 node-*/windows/python-sdk 等 job 是互补关系:GitHub Actions 管"每次 PR/push 的正确性门禁",GitLab CI 管"打 tag 触发的一次性发布动作"。
常见问题/易踩坑
- 把覆盖率不足当成"要补测试",而不先检查是不是死代码——
docs/testing.md明确提醒"An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on"。 - 忘记
test:web在 CI 里是只读回放模式——本地跑test:web:refresh才能刷新快照,直接在 CI 环境变量里改DSH_SNAPSHOT不会生效,而且这类改动一定要求人工审查每一个 diff。 - 以为本地 lefthook 全绿就等于 CI 会全绿——lefthook 故意只覆盖"本地能快速验证"的子集,
pre-push只跑 typecheck,完整的覆盖率门禁、Windows 矩阵、快照回归都只存在于 CI。
小结
DeepSeek Harness 的测试体系用七层 Vitest 配置(课程写作时是五层,后来新增了 expected 和 bench 两层)分别验证"代码区域自身正确"(unit)、"逐文件真的被跑过"(coverage)、"对着真实模型真的能用"(e2e)、"构建产物的确定性输出没有偏差"(expected)、"关键路径的性能预算没有退化"(bench)、"外部契约没有意外变化"(snapshot)、"浏览器渲染出来的真实效果没有回归"(web),每一层都对应 docs/testing.md 里一条可验证、有真实事故背书的测试哲学,而不是抽象的质量口号。CI 层面,scripts/run-gates.ts 把门禁的依赖图和调度逻辑从 YAML 里抽出来变成普通 TypeScript 程序,GitHub Actions 只负责触发具名模式并在 all-checks-passed 里汇总 required jobs(现在多了新的 bench 门禁,Windows 也拆成了 build/native-tests 两个独立 job,汇总 job 本身还要跟着自托管失败转移开关重新定位);lefthook 承担"本地几秒内能跑完"的快反馈,和 CI 的完整矩阵形成互补而非重复;.gitlab-ci.yml 则专职处理与 PR 门禁完全无关的 Python wheel 发布流程(runtime wheel 的平台覆盖已经从三个扩展到五个)。
参考文档
- Primers 编程伙伴/Bash/帮助手册/cat
- Primers 编程伙伴/Python/内建函数/all
- Primers 编程伙伴/Bash/帮助手册/true
- Primers 编程伙伴/Bash/帮助手册/local
- Primers 编程伙伴/Bash/帮助手册/test
- Primers 编程伙伴/Bash/帮助手册/export
- Primers 编程伙伴/Python/内建函数/bin
- Primers 编程伙伴/Bash/帮助手册/find
- Primers 编程伙伴/Bash/帮助手册/grep
- Primers 编程伙伴/HTML/HTML 元素/code
- Primers 编程伙伴/Python/内建函数/id
- Primers 编程伙伴/Bash/帮助手册/command
- Primers 编程伙伴/HTML/HTML 元素/pre
《LLM之Agent(九十八)|DeepSeek-Harness(八)测试策略与 CI 门禁》 是转载文章,点击查看原文。