跳转至

编写和添加测试

在归属边界处证明行为

优先通过真实生产所有者进行聚焦的集成测试,并使用确定性的外部 I/O 测试夹具,而不是模拟内部决策或整个产品启动。保持独立的单元测试契约和成本预算。

  • 行为: 指明调用方可见的契约、可信的回归以及该边界无法证明的内容。使用独立的期望值;以调用方相同的方式执行接口。原始存储断言、调用次数、顺序和精确字节,只有在保护存储、计费、投递或协议契约时才适用。
  • 反馈: 按垂直切片工作:失败行为、最小连贯修复、通过证明。确认回归失败源于原始缺陷,而不是夹具设置;报告不可用的基线证明。在绿色测试下重构。只有在检查是否存在不同契约或边界情况后,才替换冗余测试。
  • 请求: 在真实组装后捕获最终序列化负载和已解析路由。比较指令/开发者消息、工具/顺序、输入前缀、模型参数、缓存标识、端点和认证模式。热前缀复用共享一个准备所有者;记录允许的差异。独立摘要需要一个有意设计的独立契约,而不是意外的缓存复用。
  • 付费工作: 付费提供商的结果要么保留,要么从未请求。
  • 在调用前预检可预测的失败,例如脱敏或预算检查。
  • 区分未发送、结果不确定、提供商已完成和本地已持久化。核对不确定的结果;恰好一次声明需要外部幂等性证明。
  • 注入相关失败,并断言物理请求和观察到的使用情况,包括被拒绝的结果。本地处理错误绝不能静默地触发另一次调用。
  • 保留有效结果,同时不绕过脱敏、取消或权限。
  • 恢复: 通过实际的诊断消费者断言已脱敏的原因和结果。对意外降级发出警告;预期恢复可以使用已记录的结构化结果。持久化会改变未来重放的决策,然后重建并执行下一个请求,而不仅仅是模拟保存调用。在相关时覆盖压缩、切换和并发编辑;瞬时错误不是永久禁止。
  • 默认值: 枚举受影响的路由、认证模式、能力和存储状态。通过执行资格所有者执行受支持和不受支持的情况,而不是复制的能力表或预计算的允许标志。
  • 测量: 用可比较的请求数、输入/缓存/输出 token 和延迟(如相关)支持成本/性能声明;指明模型、路由和条件。实时缓存/计费声明需要实时证据;标注本地估计。现有的实时证明要求适用,而不是为无关编辑进行付费基准测试。

使用合成内容,并将凭据排除在捕获之外。从变更的契约中选择失败用例,而不是通用矩阵。如果证明需要许多私有控制,检查碎片化所有权,而不是添加仅用于测试的导出。

测试临时目录

对于测试拥有的临时目录,使用 test/helpers/temp-dir.ts 中的共享辅助函数,使所有权明确,清理保持在测试生命周期内:

import { afterEach } from "vitest";
import { useAutoCleanupTempDirTracker } from "../helpers/temp-dir.js";

const tempDirs = useAutoCleanupTempDirTracker(afterEach);

it("uses a temp workspace", () => {
  const workspace = tempDirs.make("openclaw-example-");
  // use workspace
});

useAutoCleanupTempDirTracker(afterEach) 有意不暴露手动清理方法 - Vitest 在每个测试后负责清理。旧的底层辅助函数(makeTempDir、cleanupTempDirs、createTempDirTracker)仍然存在,用于尚未迁移的测试;避免它们的新用法,并避免新的裸 fs.mkdtemp* 调用,除非测试明确验证原始临时目录行为。当确实需要裸临时目录时,添加一条可审计的允许注释并说明原因:

// openclaw-temp-dir: allow verifies raw fs cleanup behavior
const workspace = fs.mkdtempSync(prefix);

node scripts/report-test-temp-creations.mjs 报告新增 diff 行中的新裸临时目录创建和新手动共享辅助函数用法,而不阻止现有清理风格。它遵循与 scripts/changed-lanes.mjs 相同的测试路径分类,并跳过共享辅助函数实现本身。check:changed 对变更的测试路径运行此报告,作为仅警告的 CI 信号(GitHub 警告注释,而非失败)。

对于测试稍后直接执行的测试夹具树(PATH 上的桩、shebang 包装器、原生二进制文件),使用 test/helpers/close-on-exec-copy.ts 中的 copyTreeCloseOnExec 进行复制,而不是没有 filter 的递归 fs.cpSync。在 Node 24 上,该复制路径打开文件时没有 close-on-exec,因此另一个 Vitest 线程在复制中途 fork 的子进程会保持文件可写,稍后的 execve 会以 ETXTBSY 失败。

代理可靠性评估(技能)

我们已经有一些 CI 安全的测试,其行为类似于“代理可靠性评估”:

  • 通过真实 Gateway 和模拟 OpenAI 提供商进行代理准入、run-ID 响应和中止请求(src/gateway/gateway.test.ts)。
  • 端到端向导流程,验证会话接线和配置效果(src/gateway/gateway.test.ts)。

技能仍然缺少以下内容(参见 技能):

  • 决策: 当技能列在 prompt 中时,代理是否选择正确的技能(或避免无关技能)?
  • 合规性: 代理是否在使用前读取 SKILL.md 并遵循必需的步骤/参数?
  • 工作流契约: 多轮场景,断言工具顺序、会话历史延续和沙箱边界。

未来评估应首先保持确定性:

  • 一个使用模拟提供商的场景运行器,断言工具调用 + 顺序、技能文件读取和会话接线。
  • 一套小型的技能聚焦场景(使用 vs 避免、门控、prompt 注入)。
  • 可选的实时评估(可选加入、环境变量门控)仅在 CI 安全套件就位后进行。

成本预算

CI 按所属领域选择测试,因此每个 PR 的成本会被反复支付。预算以单 worker 下 pnpm test <file> --maxWorkers=1 测量:

  • 每个文件的测试时间目标低于 5 秒。超过 30 秒时,PR 正文需说明哪个契约需要该时间,以及为什么没有更便宜的层级可以证明它。
  • 需要超过其规划器每作业预算的文件不能与其他文件共享该预算,并且可以设置其作业的墙钟时间。按所有者边界拆分,或考虑仅发布层级(scripts/lib/ci-node-test-plan.mts 中的 RELEASE_ONLY_* 集合)。权衡无关 PR 破坏其契约的可能性,以及在发布时检测该故障的成本。未变更的测试套件本身可以提供发布前证明;不需要独立的重复发布测试。仅因慢并不足以删除覆盖。
  • 维护者工具家族在混合快速配置中使用 RELEASE_ONLY_TOOLING_SHARDS 和匹配的维护者叶子:仅产品 PR 和 main 省略它,工具所有者 PR 选择其受影响文件(对未解析的所有者使用全家族回退),手动 CI 和 Full Release Validation 保留它。将测试保留在其规范配置中,并保留其进程和计时器策略,以便新文件继承相同的所有者路由。专用产品 E2E 和实时测试仍位于该层级之外。参见 Node 测试泳道。
  • 在所有者处使用注入时钟,而不是真实计时器、睡眠或轮询;通过 src/test-utils/port-claims.ts 声明端口;为每个文件提供独立状态目录;复用套件级 Gateway 和进程 fixture,而不是每个测试启动;导入插件或模块的窄测试 API,而不是其完整 barrel。不要添加串行 Vitest 配置或 worker 固定:修复需要它们的共享状态。
  • 在收集时加载编译子进程声明(scripts/lib/vitest-worker-declarations.mts)。Vitest 调用中的第一次此类加载会准备整个编译 worker 生成(热时几十秒,冷时几分钟),因此在测试或钩子中 await import() 其图到达声明的测试或钩子会在测试或钩子截止时间内部花费该准备时间。静态导入主题;每个测试重新导入它的套件在 core 中添加 src/test-utils/prepare-compiled-subprocesses.ts 的副作用导入。扩展测试改用 import "openclaw/plugin-sdk/compiled-subprocess-testing";。仅将预加载添加到已经加载声明的套件。
  • 对于每个新增或实质性变更的测试文件,在 PR 中说明测量成本,并在运行存在后说明 CI 秒数。

withTestTimeout 和 raceWithTimeoutResult 是遗留的墙钟竞争;check:test-timeout-race-ratchet 保持它们在 config/test-timeout-race-baseline.txt 中的每文件计数仅收缩。使用 test/helpers/promise.ts 中的 awaitGateBeforeSettlement(gate, operation, message) 或 withinTest(work, signal) 等待拥有的完成信号,或通过所有者的注入时钟接缝使用 vi.useFakeTimers()。移除站点后,运行 pnpm check:test-timeout-race-ratchet --prune 以收缩基线。

模块 mock 与导出完整性

新的第一方 vi.mock 和 vi.doMock 工厂在 fixture 只需要覆盖少数函数时,应保留真实模块的导出:

vi.mock("./runtime.js", async (importOriginal) => ({
  ...(await importOriginal<typeof import("./runtime.js")>()),
  start: vi.fn(),
}));

仅为导出完整性使用透传。importOriginal 和 vi.importActual 可能返回有状态单例的单独模块实例;它们不保证共享状态或生命周期同一性。当隔离真实状态或初始化是 fixture 的目的时,保留封闭 mock,并在 mock 调用上方紧邻的一行说明该契约:

// mock-isolation: Keep the database and process-wide cache outside this fixture.
vi.mock("./runtime.js", () => ({ start: vi.fn() }));

pnpm check:test-mock-exports 检查字面第一方模块注册,包括相对、workspace-package 和 TypeScript 路径别名。没有可识别的真实模块返回/展开的工厂需要注释,包括语法检查无法证明的间接工厂。现有未注释工厂具有精确的源目标和 token 指纹基线;新增或变更的工厂不能借用其他站点的许可。移除或注释现有工厂后,运行 pnpm check:test-mock-exports --prune 以收缩该基线。此守卫与现有 CI 棘轮和 check:changed 一起运行;它不会重写测试。

原始 SQLite 状态访问

closeOpenClawStateDatabaseForTest() 同步关闭原生句柄,但 worker 支持的状态写入(插件状态、延迟插件迁移和其他 worker 存储)保留一个 worker 连接,其退役仅在该调用时开始。其最终关闭会在任意稍后时间以独占锁检查点并删除 WAL。在通过原始 DatabaseSync 打开数据库,或复制、哈希或快照其文件之前,await closeOpenClawStateDatabaseAsync()(或来自 src/test-utils/database-cleanup.ts 的 closeStateDatabaseForTest(),它还会清除故障闩锁)。否则原始连接可能以 SQLITE_BUSY 失败,或快照可能在测试下方变化。在原始连接上执行 PRAGMA locking_mode=EXCLUSIVE; BEGIN EXCLUSIVE 可证明没有其他连接剩余。

Skills watchers

skills.status 和技能快照准备会启动真实的 @openclaw/fs-safe watcher。在共享 worker 泳道中,非隔离 runner 会关闭文件遗留的任何 watcher,并以 skills watchers failed 使该文件失败;否则其重新武装的计时器会落在后续文件的假时钟上,并中止其 vi.runAllTimersAsync()。在 afterEach 中用 closeSkillsWatchers(true) 关闭它们,或者当测试不验证监视时设置 skills.load.watch: false。

不稳定问题分诊

没有相关变更的失败即为缺陷。切勿通过重新运行、重新推送或刷新来让结果变绿。

  1. 首先按失败分片的文件顺序复现(计划中的文件列表在作业日志中),然后单独复现。仅顺序相关的失败是来自先前文件的共享状态泄漏。
  2. 分类:夹具(临时状态、端口、cwd、env、模块单例)、顺序(断言先于所属完成信号)或产品(真实竞态)。
  3. 在所有者处修复。产品竞态需要添加一个在原始缺陷上失败的回归测试;夹具泄漏应在夹具所有者处修复,而不是在失败的测试中修复。
  4. 证明标准:该文件 20 次干净的独立运行、原始分片 3 次干净运行,以及所有者的同级测试。在 PR 中记录根本原因。
  5. 如果所有者是另一条泳道或 PR,请引用该修复;这是继续处理红色作业的唯一理由。

添加回归测试(指南)

对于清单增长和容量回归测试,将有界合成清单和固定时序数据通过真实规划器传递。将夹具置于容量边界,并保留覆盖率、所有权和执行预算断言。将真实检出清单覆盖率保留在其集成测试中,而不是为每个合成变体重建不断增长的仓库计划。

当你在线上发现并修复提供商/模型问题时:

  • 尽可能添加 CI 安全的回归测试(mock/stub 提供商,或捕获确切的请求形状转换)
  • 如果问题本质上仅限线上(速率限制、认证策略),保持线上测试范围狭窄,并通过环境变量选择加入
  • 优先选择能触达缺陷的最小生产组合:
  • 提供商请求转换/重放缺陷 -> 使用捕获的最终请求的真实适配器
  • 网关会话/历史/工具流水线缺陷 -> CI 安全的 Gateway 集成夹具,外加必需的线上证明
  • 孤立的解析器/算法缺陷 -> 针对其独立契约的聚焦单元测试
  • SecretRef 遍历护栏:
  • src/secrets/exec-secret-ref-id-parity.test.ts 从注册表元数据(listSecretTargetRegistryEntries())中为每个 SecretRef 类派生一个采样目标,然后断言遍历段 exec id 会被拒绝。
  • 如果你在 src/secrets/target-registry-data.ts 中添加新的 includeInPlan SecretRef 目标族,请更新该测试中的 classifyTargetClass。该测试会故意对未分类的目标 id 失败,因此新类无法被静默跳过。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw