- TECHNICAL_ARCHITECTURE: §2.2 exec_error/背压/硬截止数据流、§3.3 action union、 §4.4 连接池重写(busy 计数+在途去重)、§4.5 MCP ACL fail-closed、§5 超时矩阵 15s - TESTING: journeys 24→26、unit 31 入册、§5.1 mock helpers v2.1.4 契约、 映射表补 25/26 行、整改清单补 v2.1.2–v2.1.4 行 - DESIGN: roadmap 补 v2.1.1–v2.1.4 四行 - METHODOLOGY: 修复双重「## 三」编号冲突(ADR→§4,清单→§5,参考文献→§6; 2.5–2.8→3.5–3.8);新增 ADR-4.4(KB ACL fail-closed vs SDB fail-open, 按可逆性定方向)+ ADR-4.5(连接池去重/硬截止/背压) - 交叉引用修正: README §3→§4 ADR、AGENTS §2.2→§3.2、checklist §4 24项→§5 17项 - README 徽章 400+→540+(实际 546 passed / 3 skipped)
26 KiB
DGAgent 测试原则
写给读者的说明: 本文是 DGAgent 测试套件的设计契约。每条原则后括注其权威来源,并对当前套件中违反该原则的具体反模式做平铺直叙的点名——这样后续维护者一眼能看出哪些测试必须重写、哪些是合格的。
原则采用"陈述 + 反模式 + 正例"三段式,避免抽象口号。所有反模式点名基于 v0.3 套件快照,后续修复后请同步更新本文件。
一、原则总表
| # | 原则 | 来源 |
|---|---|---|
| 1 | Red / Green / Refactor 三拍循环 | Beck 2002 |
| 2 | 测试越像使用方式,越值得信任 | Dodds 2018 |
| 3 | 测试金字塔:集成层最多,UI/E2E 最少 | Cohn 2009 / Fowler 2012 |
| 4 | 不要测试 Mock,测试你的代码 | Rainsberger 2009 |
| 5 | 在系统边界 Mock,不要在内部 Mock | Fowler 2007 |
| 6 | 优先状态验证,而非行为验证 | Fowler 2007 / Meszaros 2007 |
| 7 | 一个测试一个断言条件 | Meszaros 2007 |
| 8 | 四段式结构:Setup / Exercise / Verify / Teardown | Meszaros 2007 |
| 9 | 永远不要测试实现细节 | Dodds 2019 |
| 10 | 静态分析先于测试 | Dodds 2021 |
| 11 | 测试必须快,提交套件 ≤10 分钟 | Beck 2002 / Fowler 2014 |
| 12 | 确定性不可妥协——同输入同输出 | Paseo 2025 |
二、原则详解与反模式点名
1. Red / Green / Refactor — Kent Beck, TDD by Example (2002)
写一个失败的测试 → 用任何手段让它通过 → 消除在让测试通过时引入的重复。
为什么重要: Red 阶段证明测试能失败(否则它是死代码);Green 证明功能存在;Refactor 保证代码干净。没有 Red 阶段的测试只是"对已经能跑的代码加注释"。
正例: tests/unit/sdb-gate.test.ts — 先写"fatal 命令应被拒"的失败断言,再让 assessRisk 通过。这是套件中 TDD 流程产物的范本。
反模式(v0.3 旧版): 04-kb-search.test.ts / 05-model-route.test.ts / 08-dispatch-expert.test.ts — 这些测试从未失败过,因为它们测的是 mock 函数,而 mock 函数被写死返回特定值。删除 mock 中的 return { title: "RDK X5" },测试就挂;改 mock 返回别的,测试照样过。这是同义反复,不是测试。已在 v0.3 重构中删除。
2. 测试越像使用方式,越值得信任 — Kent C. Dodds (2018)
The more your tests resemble the way your software is used, the more confidence they can give you.
为什么重要: 用户不会调用 mockKbSearch,他们会通过 pi agent 触发 dg_kb_search 工具。测试应该穿过工具的公共 API,而不是绕过它直接调内部函数。
正例: tests/journeys/01-install.test.ts — 通过 providerFactory(pi) 触发注册流程,验证 pi.__calls.providers 的内容。这模拟了 Pi 启动时的真实路径。
反模式: 旧 04-kb-search.test.ts 直接 import 并调用 mockKbSearch,没有穿过任何真实代码层。当 v0.4 把 dg_kb_search 换成真实 MCP 调用时,这个测试一行都不会改——因为它根本没在测系统。
3. 测试金字塔:集成层最多,UI/E2E 最少 — Cohn (2009) / Fowler (2012)
写不同粒度的测试。越高层的测试数量应该越少。没有 service-level 测试填补 unit 和 UI 之间的空隙,所有测试都会挤在 UI 层——昂贵、脆弱、慢。
为什么重要: DGAgent 没有 UI,"UI 层"等价于 agent 与用户的交互。E2E 测试需要真实 RDK 板卡,昂贵且无法在 CI 跑。绝大多数测试应在集成层:mock 掉 SSH/mDNS/网络,但内部代码真实运行。
正例: v0.3 重构后的目录分布——tests/smoke.test.ts(基础)+ tests/journeys/*.test.ts(集成层)+ tests/unit/*.test.ts(单元层)。
反模式: 旧 smoke.test.ts 第 38-77 行用 toBeTypeOf 检查导出存在——这是单元测试最底层,但只验证"导出存在"。这种夹生测试应该删掉或升级为行为测试。
4. 不要测试 Mock,测试你的代码 — Rainsberger (2009)
Integrated test 是任何结果依赖多于一个非平凡行为的测试。它们不可靠、自我复制、浪费时间。用 collaboration test(带 test double)+ contract test(验证 double 与真实服务匹配)替代。
为什么重要: 如果一个测试的成败完全由 mock 实现决定,那么它测的是 mock 作者的记忆,不是系统的正确性。
正例: tests/unit/sdb-gate.test.ts 测真实 assessRisk;tests/journeys/08-board-discovery.test.ts 测真实 discoverBoards、loadBoardConfig、saveBoardConfig。这些测试若失败,必然是生产代码出问题。
反模式(v0.3 旧版已删除):
- 旧
04-kb-search.test.ts— 全文件 4 个测试都在断言mockKbSearch返回它被写死的值 - 旧
05-model-route.test.ts— 同上,断言mockModelRoute的硬编码返回 - 旧
08-dispatch-expert.test.ts— 同上,断言mockDispatchExpert的硬编码返回
处理建议: v0.4/v0.5/v0.6 把这些 mock 换成真实实现时,写新的集成测试。这些 mock 测试的输入/输出契约应该在 v0.2 就锁定(contract test 思想),而不是让 mock 测试伪装成系统测试。
5. 在系统边界 Mock,不要在内部 Mock — Fowler, "Mocks Aren't Stubs" (2007)
Classical TDD 风格:能用真实对象就用真实对象,只有当协作对象"尴尬"时才用 test double。Mockist 风格:任何有有趣行为的对象都 mock。Mockist 测试更耦合实现——改协作对象的调用方式常常破坏 mockist 测试。
为什么重要: DGAgent 的"系统边界"是 ssh2、bonjour-service、node:fs、node:crypto、Pi 的 ExtensionAPI。这些是外部世界,mock 它们是对的。但内部模块(utils.ts 里的 discoverBoards、execOnBoard、assessRisk)不应该被 mock——它们就是被测对象。
正例: tests/journeys/07-file-sync.test.ts mock 掉 ssh2 的 SFTP 通道,但让 sftpPush/sftpPull 的真实代码跑——参数校验、错误路径、文件写入路径都走真实逻辑。
反模式: 旧 06-ssh-exec.test.ts 第 3-10 行定义了 mockExecResult 但从未使用——这是 mock 设计混乱的征兆。Mock 的边界应该是清晰的(ssh2.Client 的 connect/exec/end 三个方法),而不是把 mock 数据也提到测试文件顶部当常量。已在 v0.3 重构中删除死代码。
6. 优先状态验证,而非行为验证 — Fowler (2007) / Meszaros (2007)
状态验证:检查 SUT 的最终状态是否正确。行为验证:检查 SUT 是否按预期调用了协作对象。能用状态验证就用——它对实现细节耦合更少。
为什么重要: 断言 pi.__calls.providers[0].name === "dg-robot"(状态)比重构后仍能通过;断言"registerProvider 先于 registerTool 被调用"(行为)在调换顺序后就挂——但这种调换可能根本不影响正确性。
正例: tests/journeys/02-mode-selection.test.ts 检查 pi.__calls.entries 中是否存在特定 mode 的 entry——这是状态验证。
反模式: 当前套件还没出现严重的行为验证反模式,但 helpers/mock-pi.ts 的设计鼓励了这种用法——它记录所有调用的数组,调用者很容易写"断言第 N 次调用的第 M 个参数"这种脆性测试。
7. 一个测试一个断言条件 — Meszaros (2007)
每个 Scripted Test 应该验证一个测试条件。多个测试需要相同 fixture 时,用 Implicit Setup(beforeEach),而不是把多个条件塞进一个测试。
为什么重要: 一个测试失败时,测试名应该立即告诉你什么坏了。"写入文件 + 注册 provider" 失败时你不知道是写文件挂了还是注册挂了。
正例: tests/journeys/02-mode-selection.test.ts 的 4 个测试每个只断言一件事:beginner 模式设置、free 模式设置、会话恢复、默认回退。
反模式(v0.3 旧版已修复): 旧 03-dg-setup-wizard.test.ts 第 72 行测试名为 "writes env vars to settings.json + registers provider at runtime"——名字里的 + 是红牌。这个测试同时断言了文件系统副作用和 Provider 注册。已拆成两个独立测试。
8. 四段式结构:Setup / Exercise / Verify / Teardown — Meszaros (2007)
每个测试按顺序走四步:fixture setup → exercise SUT → result verification → fixture teardown。
为什么重要: 视觉上能区分"arrange / act / assert"的测试就是好的 spec。如果一个测试的四段混在一起,说明它在测多件事。
正例: tests/journeys/07-file-sync.test.ts 的 push 测试:Setup(创建临时文件)→ Exercise(调用 dg_file_sync)→ Verify(断言 SFTP 收到数据 + 文件被读到远程)→ Teardown(finally 删除临时文件)。四段清晰可见。
反模式: 旧 03-dg-setup-wizard.test.ts 的 beforeEach 里做了 settings.json 备份,afterEach 里恢复——fixture 管理是对的,但测试体内同时验证文件写入和 Provider 注册,破坏了"Exercise 后只 Verify 一件事"的纪律。
9. 永远不要测试实现细节 — Dodds (2019)
如果你的测试做了消费者不会做的事,那它在测实现细节。如果重构破坏了测试,那它在测实现细节。重构时几乎不应该改测试。
为什么重要: DGAgent 的"消费者"是 Pi agent。它只关心 pi.registerTool(...) 注册的工具能不能被调用并返回正确结果——不关心工具内部用了哪个 SSH 库、哪个连接池实现。
正例: tests/unit/sdb-gate.test.ts 不关心 assessRisk 是同步还是异步、用 regex 还是 AST、缓存与否——只关心输入命令 + 用户上下文 → 输出风险等级。重构 assessRisk 内部不会破坏测试。
反模式: 旧 smoke.test.ts 第 38-77 行用 toBeTypeOf('function') 检查导出存在——这测的是"模块系统工作正常",不是 DGAgent 的行为。即使把 discoverBoards 的实现整个删掉只留空函数,这些测试照样过。
10. 静态分析先于测试 — Dodds, "The Testing Trophy" (2021)
静态测试工具——类型检查器(TypeScript)和 linter(ESLint)——能在你写代码时就抓住拼写错误和类型错误。它们是测试奖杯的底座:最便宜、最快的层。
为什么重要: npm run typecheck 必须在任何测试运行前通过。这是第一道闸门。strict: true + noUncheckedIndexedAccess: true + noImplicitOverride: true 能抓住 null 引用、拼写错误的导出名、错误的参数类型。
正例: tsconfig.json 已配置 strict 三件套。CI 应该跑 npm run typecheck && npm test,typecheck 失败就不跑测试。
反模式: tests/helpers/mock-pi.ts:35 的 as unknown as MockPi 是对类型系统的投降——它告诉编译器"别管了,我知道我在干什么"。这破坏了静态分析这一层。应该用 satisfies MockPi 或显式声明类型。已在 v0.3 重构中修复。
11. 测试必须快 — Beck (2002) / Fowler, "UnitTest" (2014)
Commit suite 应该在 10 分钟内跑完。重点是:你的套件应该快到你不至于嫌麻烦而不愿频繁跑它。
为什么重要: 测试套件 + mock 掉了所有外部依赖,应该在秒级跑完。如果某天 SSH 集成测试加了真实板卡连接,5s 超时可能不够——但那应该是 E2E 层,不在 commit suite。
正例: vitest.config.ts 配了 mockReset: true + restoreMocks: true,保证测试间隔离。
反模式(潜在): vitest.config.ts 没有配 testTimeout,默认 5000ms。当真实 SSH 集成测试加入时,应该明确配 testTimeout: 10000。也不要漏 clearMocks: true——restoreMocks 只恢复 spy 实现,不清空调用记录。
12. 确定性不可妥协——同输入同输出 — Paseo (2025)
测试每次运行必须产生相同的结果。不能有条件断言、不能依赖时间/随机/网络抖动、不能用
toBeTruthy/toBeDefined这种弱断言。
为什么重要: Flaky test 是测试套件最危险的毒——它让开发者学会"忽略红色",最终整个套件失去信用。
正例: tests/unit/sdb-gate.test.ts 用具体字符串断言 r.level === "fatal"、r.confirmation_required === false,不用 toBeTruthy。
反模式:
- 旧
smoke.test.ts的toBeTypeOf('function')是弱断言——它只验证存在性,不验证行为 - 旧
06-ssh-exec.test.ts第 3-10 行的mockExecResult是死代码——未使用的变量暗示作者没想清楚 mock 要返回什么 - 任何依赖
Date.now()/Math.random()/ 真实网络调用的测试都违反此原则。用vi.useFakeTimers()替代真实时间
三、套件整改清单(按优先级)
基于上述原则对 v0.3 测试套件的整改清单。✅ 表示 v0.3 重构已修复;📍 表示后续版本处理。
| 优先级 | 文件 | 问题 | 对应原则 | 整改动作 |
|---|---|---|---|---|
| ✅ v0.3 | 旧 04-kb-search.test.ts |
全文件测 mock | #4 | 已删除,v0.4 真实 KB 上线时写集成测试 |
| ✅ v0.3 | 旧 05-model-route.test.ts |
全文件测 mock | #4 | 已删除,v0.5 真实路由表上线时写集成测试 |
| ✅ v0.3 | 旧 08-dispatch-expert.test.ts |
全文件测 mock | #4 | 已删除,v0.6 真实 dispatch 上线时写集成测试 |
| ✅ v0.3 | 旧 03-dg-setup-wizard.test.ts:72 |
测试名含 +,测两件事 |
#7 | 已拆成两个独立测试 |
| ✅ v0.3 | 旧 03-dg-setup-wizard.test.ts |
写入 ~/.pi/agent/settings.json |
#5(边界) | 已改用 os.tmpdir() + 临时目录 |
| ✅ v0.3 | 旧 10-board-discovery.test.ts |
写入 ~/.pi/agent/dgagent-boards.json |
#5(边界) | 已改用 os.tmpdir() |
| ✅ v0.3 | 旧 06-ssh-exec.test.ts:3-10 |
mockExecResult 死代码 |
#12 | 已删除 |
| ✅ v0.3 | 旧 mock-pi.ts:35 |
as unknown as MockPi |
#10 | 已改用 satisfies 或显式类型 |
| ✅ v2.1.1 | smoke.test.ts |
toBeTypeOf 弱断言 |
#9、#12 | 已升级:assessRisk 真实行为断言(safe/fatal),弱断言删除 |
| ✅ v2.1.1 | vitest.config.ts |
缺 clearMocks、testTimeout 等 |
#11 | 已补齐:clearMocks + mockReset + restoreMocks + testTimeout: 10000 |
| ✅ v1.0 | 全套件 | 缺 tests/e2e/ 真实板卡集成测试目录 |
#3 | ✅ 已建 tests/e2e/mocked/(链式,默认跑)+ tests/e2e/real/(DG_E2E_BOARD_ID 门控,npm run test:e2e)+ README.md |
| ✅ v2.1.2–v2.1.4 | 测试盲区(三轮 review 发现) | SFTP 错误路径、连接池并发、命令注入、ACL fail-closed、词边界、输出 Gate 降级、compact 边界、runner 审计、模式恢复、--since 校验均无测试 | #3、#4、#12 | ✅ 已补 11 个新测试文件(见映射表"二轮加固单元"行 + journeys 25/26 + cli-since/sftp-failures 等),546 passed / 3 skipped |
四、目录结构(v0.3 重构后)
tests/
├── helpers/ # shared mock + setup infrastructure
│ ├── mock-pi.ts # MockPi + MockCtx + asExt
│ ├── mock-ssh.ts # ssh2 Client/Channel/SFTP mock + connectFail/channelOpts/sftpOpts + v2.1.4:pullError/pushError 注入、clients[]+triggerMockClientEvent、connect 阻塞、write→boolean/pause/resume
│ ├── mock-bonjour.ts # bonjour-service mDNS mock
│ ├── tmp-fs.ts # os.tmpdir() 隔离的临时文件系统 + 8 路径注入(boards/settings/session/audit/candidates/workflows/generated/kb-drafts)
│ ├── journey-setup.ts # setupJourney() — bonjour mock + resetModules + tmpFs lifecycle
│ ├── tool-exec.ts # getToolExecute(tmp, name) — load tools factory + return execute fn
│ └── system-prompt-loader.ts # loadSystemPrompt + findHandler + findCommand
├── smoke.test.ts # package metadata + assessRisk 行为断言(v2.1.1 升级)
├── journeys/ # integration tests(26 个,journey→test 一一对应,见下方映射表)
├── unit/ # unit tests(31 个纯逻辑测试:sdb-gate/observability/detector/generator/registry/autoloop/runner/compact/mode-gate/build-verify/push-and-verify/board-health/telemetry/mcp-server/gates/safe-exec/routing/tool-exec/render/camera-check/debug/log-rotation/telemetry-extension/mock-ssh + v2.1.4 新增:ssh-pool/build-verify-security/mcp-client/routing-boundary/output-gate/runner-audit/sftp-failures)
└── e2e/ # mocked(真实 HTTP server / spawn 真实 CLI / 链式多工具,默认跑)+ real/(真实板卡,DG_E2E_BOARD_ID 门控)
旅程 → 测试文件 映射(一一对应)
| DESIGN.md 旅程 | 行号 | 测试文件 |
|---|---|---|
| 安装与首次启动 | L262 | tests/journeys/01-install.test.ts |
| 新手模式 vs 自由模式 | L286 | tests/journeys/02-mode-selection.test.ts |
| 动态模式切换 | L312 | tests/journeys/03-mode-switch.test.ts |
| 自由模式下的连接诊断 | L319 | tests/journeys/04-connection-diagnostics.test.ts |
| 嵌入式高危操作分级确认 | L329 | tests/journeys/05-high-risk-confirmation.test.ts |
| SSH 命令执行 | req 3 | tests/journeys/06-ssh-exec.test.ts |
| 文件同步 | req 3 | tests/journeys/07-file-sync.test.ts |
| 板卡发现 | req 3 | tests/journeys/08-board-discovery.test.ts |
| /dg-setup 引导 | req 5 | tests/journeys/09-setup-wizard.test.ts |
| 知识库检索 | req 1 | ✅ tests/journeys/14-kb-search.test.ts(MCP fetch mock + ACL 过滤) |
| 模型路由 | req 2 | ✅ tests/journeys/10-model-route.test.ts |
| 专家调度 | req 4 | ✅ tests/journeys/11-dispatch-expert.test.ts |
| 相机检查 | req 6 | ✅ tests/journeys/12-camera-check.test.ts |
| 安全执行 | req 7 | ✅ tests/journeys/13-safe-exec.test.ts |
| 推送并验证 | §9.3 Layer 1 | ✅ tests/journeys/15-push-and-verify.test.ts |
| 板卡健康 | §9.3 Layer 1 | ✅ tests/journeys/16-board-health.test.ts |
| 编译验证 | SDB Gate #4/#6 | ✅ tests/journeys/17-build-verify.test.ts |
| 模式评估 | SDB Gate #8 | ✅ tests/journeys/18-mode-evaluate.test.ts |
| 工具使用观测(v0.5→v1.3) | §9.4 | ✅ tests/journeys/19-usage-report.test.ts(/dg-usage 排行表 + 失败率 + 趋势 + --board/--since/--json) |
| 脚本候选识别(v1.4) | §9.4 v0.6 | ✅ tests/journeys/20-suggest-candidates.test.ts(/dg-suggest 序列挖掘 + 候选持久化 + --min/--json) |
| 生成 + 信任分级(v1.5) | §9.5 | ✅ tests/journeys/21-accept-candidate.test.ts(/dg-accept 生成骨架 + 注册 auto)+ tests/journeys/22-registry.test.ts(/dg-registry promote/safe-run) |
| 全自动闭环(v2.0) | §9.4 v1.0 | ✅ tests/journeys/23-autoloop.test.ts(/dg-autoloop 闭环 + 幂等 + dry-run + session_start 自动触发)+ tests/unit/autoloop.test.ts(runAutoLoop/collectKbDrafts) |
| 执行载体(v2.1) | §9.5 | ✅ tests/journeys/24-workflow-run.test.ts(dg_workflow_run auto 确认/安全执行/未知 workflow/fatal + v2.1.4 exec_error 审计 + board_id 日志)+ tests/unit/runner.test.ts(序列校验/信任阶梯/SDB Gate/不支持步骤)+ tests/unit/runner-audit.test.ts(v2.1.4 逐命令 SDB 审计 + board_id 一致性守卫) |
| 模式恢复容错(v2.1.4) | req 5 | ✅ tests/journeys/25-mode-restore.test.ts(session_start 损坏条目跳过 + 回落默认 free) |
| --since 参数校验(v2.1.4) | §9.4 v0.5 | ✅ tests/journeys/26-usage-since-validation.test.ts(/dg-usage 非法 --since 可读错误) |
| 命令日志(v2.1) | §3.4 | ✅ tests/journeys/19-usage-report.test.ts(/dg-usage 写 command 事件,Model-visible ⟺ Logged) |
| 链式多工具 | 用户叙事 | ✅ tests/e2e/mocked/chained-tools.test.ts |
| MCP 服务端(v1.6) | §9.3 Layer 2 | ✅ tests/unit/mcp-server.test.ts(15)+ tests/e2e/mocked/mcp-http.test.ts(真实 HTTP server) |
| CLI(v1.6) | §9.3 Layer 2 | ✅ tests/e2e/mocked/cli.test.ts(spawn 真实 node 进程 + env 路径覆盖)+ tests/e2e/mocked/cli-since.test.ts(v2.1.4 非法 --since 一行错误 + 非零退出) |
| 真实板卡 | E2E | ✅ tests/e2e/real/board.test.ts(DG_E2E_BOARD_ID 门控) |
| 二轮加固单元(v2.1.4) | review 批次三 | ✅ tests/unit/ssh-pool.test.ts(连接池 H1 busy/H2 去重/M3 硬截止/M4 背压/L1 mkdirp)+ tests/unit/build-verify-security.test.ts(注入矩阵:;/反引号/$()/引号/换行/glob/unicode 同形字)+ tests/unit/mcp-client.test.ts(ACL fail-closed MCP_ERR_ACL_UNKNOWN)+ tests/unit/routing-boundary.test.ts(ASCII 词边界 CJK 安全)+ tests/unit/output-gate.test.ts(LLM 输出 schema 降级 fail-closed)+ tests/unit/sftp-failures.test.ts(SFTP 错误注入 reject)+ tests/unit/compact.test.ts(边界:空/单行/超限/全 error 行/CJK) |
单元测试 vs 旅程测试的边界
| 类型 | 测什么 | 不测什么 |
|---|---|---|
tests/unit/sdb-gate.test.ts |
assessRisk(cmd, ctx) 函数的纯逻辑:输入命令 + 用户上下文 → 输出风险等级 |
不穿过 Pi 工具 API;不测确认交互流程 |
tests/journeys/05-high-risk-confirmation.test.ts |
用户执行 dd 命令 → 工具拦截 → 用户确认 → 命令执行 整条旅程 |
不测 assessRisk 的所有命令分类(那是 unit 的事) |
两层互补:unit 测函数的完备性,journey 测用户体验。当 unit 失败时定位是哪条规则错;当 journey 失败时定位是哪个交互环节错。
五、实操指南:如何写一个新 Journey 测试
5.1 Helpers 速查
| Helper | 作用 | 典型用法 |
|---|---|---|
setupJourney() |
一行搞定 bonjour mock + vi.resetModules() + tmpFs 生命周期 |
const journey = setupJourney() |
getToolExecute(tmp, name) |
动态 import tools factory → 注册到 MockPi → 返回 execute 函数 | const exec = await getToolExecute(journey.tmp, "dg_ssh_exec") |
loadSystemPrompt() |
动态 import system-prompt factory | const factory = await loadSystemPrompt() |
findHandler(pi, event) |
从 MockPi 的 events 中取出指定事件的 handler | const handler = findHandler(pi, "session_start") |
findCommand(pi, name) |
从 MockPi 的 commands 中取出指定 slash command 的 handler | const handler = findCommand(pi, "dg-mode") |
installSshMock(opts) |
mock ssh2 Client(connect/exec/end + SFTP) | installSshMock({ stdout: "ok" }) |
setSshConnectFail(level) |
模拟 SSH 连接失败(auth/socket) | setSshConnectFail("auth") |
setSshChannelOpts(opts) |
按命令定制 exec 响应(stdout/stderr/exitCode/signal/execError) | setSshChannelOpts({ commands: { "uname -a": { stdout: "Linux" } } }) |
setSshSftpOpts(opts) |
SFTP push/pull 数据 + v2.1.4 错误注入(pullError/pushError,错误流不产数据) | setSshSftpOpts({ pushError: new Error("disk full") }) |
setSshConnectBlocked(b) / releaseSshConnect() |
阻塞/放行 connect "ready"(v2.1.4,控制 H2 并发时序) | setSshConnectBlocked(true) → 断言在途 → releaseSshConnect() |
triggerMockClientEvent(ev, i) |
对已记录 client 触发 close/error(v2.1.4,H1 淘汰测试) | triggerMockClientEvent("close", 0) |
resetSshMockState() |
重置全部 mock 状态(含 clients[]/connectBlocked/错误注入) | beforeEach(() => resetSshMockState()) |
createMockCtx(opts) |
创建 mock ExtensionContext(sessionId / entries / ui) | const ctx = createMockCtx({ sessionId: "test-1" }) |
5.2 模板:测试一个 dg_* 工具
以 dg_ssh_exec 为例——复制此模板,改 tool name + params + 断言即可:
import { describe, it, expect } from "vitest";
import { installSshMock } from "../helpers/mock-ssh.ts";
import { setupJourney } from "../helpers/journey-setup.ts";
// 1. 安装 SSH mock(在模块加载时执行,早于 beforeEach)
installSshMock({ stdout: "expected output" });
// 2. 一行完成 bonjour mock + resetModules + tmpFs lifecycle
const journey = setupJourney();
// 3. 延迟导入(必须在 resetModules 之后动态 import)
import { createMockCtx } from "../helpers/mock-pi.ts";
import { getToolExecute } from "../helpers/tool-exec.ts";
describe("journey N: <feature name>", () => {
it("<what this test verifies>", async () => {
// Exercise
const exec = await getToolExecute(journey.tmp, "dg_ssh_exec");
const ctx = createMockCtx({ sessionId: "test-1" });
const result = await exec(
"call-1",
{ board_id: "rdk-x5-default", command: "ls /", force: false },
undefined, undefined, ctx,
);
// Verify
const text = result.content[0]!.text;
const details = result.details as { executed: boolean; exit_code: number | null };
expect(text).toContain("expected output");
expect(details.executed).toBe(true);
expect(details.exit_code).toBe(0);
});
});
5.3 模板:测试一个 slash command
以 /dg-mode 为例:
import { describe, it, expect } from "vitest";
import { setupJourney } from "../helpers/journey-setup.ts";
const journey = setupJourney();
import { createMockPi, createMockCtx, asExt } from "../helpers/mock-pi.ts";
import { loadSystemPrompt, findCommand } from "../helpers/system-prompt-loader.ts";
describe("command test: /dg-mode", () => {
it("sets mode and appends entry", async () => {
// Setup: load factory + register into MockPi
const factory = await loadSystemPrompt();
const pi = createMockPi();
factory(asExt(pi));
// Exercise
const handler = findCommand(pi, "dg-mode");
const ctx = createMockCtx();
await handler("beginner", ctx);
// Verify: check state (not behavior)
const entry = pi.__calls.entries.find((e) => e.customType === "dg-mode");
expect(entry).toBeDefined();
expect((entry!.data as { mode: string }).mode).toBe("beginner");
});
});
5.4 检查清单
写完一个新测试后,逐条确认:
- 测试名描述一个条件(不是"works correctly")
- 只断言一件事(一个
it一个核心断言) - SSH/mDNS 在系统边界 mock,内部代码真实运行
- 用状态验证(
pi.__calls.xxx),不用行为验证(spy call counts) - 不依赖时间/随机/网络——确定性
npm run typecheckexit 0npm test新测试 pass + 旧测试不回归