测试套件和命令
快速开始¶
大多数情况下:
- 完整门禁(推送前应通过):
pnpm build && pnpm check && pnpm check:test-types && pnpm test - 在配置充裕的机器上更快地本地运行完整套件:
pnpm test:max - 直接使用 Vitest watch 循环:
pnpm test:watch - 直接指定文件目标同样可以路由插件/通道路径:
pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts - 在针对单个失败进行迭代时,优先选择定向运行。
- Docker 支撑的 QA 站点:
pnpm qa:lab:up - Linux VM 支撑的 QA 通道:
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
最后两个通道需要其他命令所不需要的工具:qa:lab:up 需要正在运行的 Docker daemon 和源码检出,因为 npm tarball 未包含 QA Lab;multipass runner 需要安装 Multipass。参见 QA 专用 runner。
当你改动测试或想要额外信心时:
- 仅供参考的 V8 覆盖率报告:
pnpm test:coverage - E2E 套件:
pnpm test:e2e
Oxlint 的 max-lines 规则会在文件超过 .oxlintrc.json 中按作用域设定的限制时发出警告;这些警告仍会出现在 lint 日志中,但不会导致 CI 失败。本地的 pnpm check:changed 会拒绝超出容量上限的变更文件,并单独检查新增违规和增长情况;全量 lint 发现的未触碰超限文件则作为警告。PR CI 也会将数值棘轮违规报告为警告。抑制基线棘轮在本地仍然严格。关于比较基线和仅可缩减维护,请参阅表层棘轮。
测试套件(什么在何处运行)¶
可以将这些套件视为“真实度递增”(同时不稳定性和成本也在递增)。
单元 / 集成(默认)¶
- 命令:
pnpm test - 配置:未指定目标的运行使用
vitest.full-*.config.ts分片集合,并可能将多项目分片扩展为按项目配置,以便并行调度 - 文件:
src/**/*.test.ts、packages/**/*.test.ts和test/**/*.test.ts下的核心/单元清单;UI 单元测试在专门的unit-ui分片中运行 - 范围:
- 纯单元测试
- 进程内集成测试(网关认证、路由、工具链、解析、配置)
- 针对已知 bug 的确定性回归
- 预期:
- 在 CI 中运行
- 无需真实密钥
- 应快速且稳定
- 解析器和公共表面加载器测试必须证明
api.js和runtime-api.js在生成的微型插件 fixture 下具备广泛的回退行为,而不是使用真实打包的插件源码 API。真实的插件 API 加载应属于插件自己的契约/集成套件。 - 原生插件解析器套件在 Node 和 Bun 上的
plugins-native-loader中运行,不经过共享的 source-loader 覆盖。全局的 Bun--tsconfig-override可以将被拒绝的 fixture 别名解析到检出源码,从而绕过该套件正在测试的所有权边界。Bun 的原生 worker 还会禁用自动包安装,从而让缺失的 fixture 依赖保持缺失。
原生依赖策略:
- 默认的测试安装会跳过可选的 Discord opus 原生构建。Discord 语音使用内置的
libopus-wasm,并且@discordjs/opus在allowBuilds中保持禁用,因此本地测试和 Testbox 通道不会编译原生 addon。 - 在
libopus-wasm基准仓库中比较原生 opus 性能,而不是在默认的 OpenClaw 安装/测试循环中比较。不要在默认的allowBuilds中将@discordjs/opus设为true;这会使无关的安装/测试循环编译原生代码。
项目、分片与作用域通道
- 未指定目标的
pnpm test会运行十三个较小的分片配置(core-unit-fast、core-unit-src、core-unit-security、core-unit-ui、core-unit-support、core-support-boundary、core-tooling、core-contracts、core-bundled、core-runtime、agentic、auto-reply、extensions),而不是一个庞大的原生根项目进程。这降低了高负载机器上的峰值 RSS,并避免 auto-reply/插件工作导致无关套件资源饥饿。 pnpm test --watch仍使用原生根vitest.config.ts项目图,因为多分片监听循环并不实用。pnpm test、pnpm test:watch和pnpm test:perf:imports会先将显式文件/目录目标路由到作用域通道,因此pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts可避免承担完整的根项目启动开销。- 非 watch 的包和智能体目录目标(例如
pnpm test packages/gateway-client或pnpm test src/agents/tools),以及带引号的智能体 glob(例如pnpm test 'src/agents/failover/**/*.test.ts'),会发现常规的*.test.ts文件并将每个文件路由到其所属通道。这保留了 fast、isolated、harness 和 database-worker 的所有权、共享排除规则以及继承的 include 限制;普通选择不会纳入 live 或 E2E 测试。 - 非 watch 的根项目运行(例如
node scripts/run-vitest.mjs run src/config)会在启动前准备所选测试所需的任何已构建运行时。 pnpm test:changed默认将变更的 git 路径展开到低成本作用域通道:直接测试编辑、同级*.test.ts文件、显式源码映射,以及本地导入图依赖项。配置/设置/包编辑不会触发全量测试,除非你显式使用OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed。pnpm check:changed是窄范围工作的常规智能本地检查门禁。它将 diff 分类为核心、核心测试、扩展、扩展测试、应用、文档、发布元数据、live Docker 工具链和工具链,然后运行匹配的类型检查、lint 和 guard 命令。所选路径还会通过pnpm test:serial安排针对性的 Vitest 所有者测试;如需与所改动契约匹配的额外测试证据,可使用pnpm test:changed或显式的pnpm test <target>。仅涉及发布元数据的版本号提升会运行针对性的版本/配置/根依赖检查,并带有防护逻辑:拒绝除顶层 version 字段之外的包变更。- 在默认针对
HEAD的 Git diff 模式下,如果仅注释/空白的 TypeScript 编辑在 token 和换行边界上与合并基线一致,则会跳过其类型检查通道和核心图边界检查。包含 TypeScript/JSX 指令、三斜线注释、解析错误或路径生命周期变更的文件会保留类型检查,JavaScript 文件同样如此。Lint、格式化、棘轮、guard 和测试保持完整的变更路径范围。暂存、显式路径和非HEAD比较保留正常的类型检查选择;--dry-run会报告所有跳过的路径。 - Live Docker ACP 测试台编辑会运行聚焦检查:对 live Docker 认证脚本进行 shell 语法检查,并对 live Docker 调度器进行 dry-run。仅当 diff 仅限于
scripts["test:docker:live-*"]时,package.json变更才会被纳入;依赖、导出、版本以及其他包表面编辑仍使用更广泛的 guard。 - 来自 agents、commands、plugins、auto-reply 辅助函数、
plugin-sdk以及类似纯工具区域的轻导入单元测试,会通过unit-fast通道运行,该通道会跳过test/setup-openclaw-runtime.ts;有状态/运行时较重的文件仍留在现有通道。 - 选定的
plugin-sdk和commands辅助源码文件还会将变更模式运行映射到这些轻量通道中的显式同级测试,从而使辅助函数编辑无需重跑该目录的完整重型套件。 auto-reply拥有专用的分组,用于顶层核心辅助函数、顶层reply.*集成测试以及src/auto-reply/reply/**子树。CI 进一步将 reply 子树拆分为 agent-runner、dispatch 和 commands/state-routing 分片,从而避免某个导入繁重的分组独占整个 Node 尾部。- 常规 PR/main CI 会故意跳过 bundled plugin 批量扫描和仅发布时运行的
agentic-plugins分片。完整的 Release Validation 会在发布候选版本上为这些插件繁重套件调度独立的Plugin Prerelease子工作流。
嵌入式运行器覆盖
- 当你更改消息工具发现输入或压缩运行时上下文时,请保持两级覆盖。
- 为纯路由和规范化边界添加聚焦的辅助函数回归测试。
- 保持嵌入式运行器集成套件健康:
src/agents/embedded-agent-runner/compact.hooks.test.ts、src/agents/embedded-agent-runner/run.overflow-compaction.test.ts以及src/agents/embedded-agent-runner/run.overflow-compaction.loop.test.ts。 - 这些套件验证作用域 ID 和压缩行为仍然通过真实的
run.ts/compact.ts路径流动; 仅靠辅助函数测试不足以替代这些集成路径。
Vitest 进程池与隔离默认值
- 基础 Vitest 配置在 Windows 上默认使用
forks,在其他平台上使用threads。 Windows 工作线程需要独立的原生句柄表:并发线程派生可能会继承另一个工作线程的临时输出管道句柄, 从而阻止该工作线程的子进程清理观察到 EOF。工作线程数量和文件并行度保持不变。 - SQLite 准入检查在每个 Vitest 工作线程中的测试收集之前运行。Bun 线程继承配置进程的决策; 操作系统 fork 则在本地方初始化该决策。Bun 在数据库池捕获其策略之前运行现有的原生关闭一致性探针; Node 保留其运行时提供的能力。
- 共享的 Vitest 配置固定使用
isolate: false,并在根项目、e2e 和 live 配置中使用非隔离运行器。 - 根 UI 泳道保留其
jsdom设置和优化器,但也在共享的非隔离运行器上运行。 - 提供者插件分片通过共享清理运行器复用工作线程。使用
vi.stubGlobal跟踪全局替换, 以便清理可以在下一个文件之前恢复它们。 - 在每次测试尝试之前以及文件清理之前,共享运行器会等待早期 teardown 未等待就调度的 agent 数据库关闭完成, 因此工作线程租约释放永远不会与下一个测试重叠。失败的关闭仍与其所有者及文件末尾排空关联,和之前一样。
- 每个
pnpm test分片都从共享的 Vitest 配置继承平台进程池和isolate: false默认值,除非其所有者另行选择。 scripts/run-vitest.mjs默认会为 Vitest 子 Node 进程添加--no-maglev, 以减少大型本地运行期间的 V8 编译抖动。设置OPENCLAW_VITEST_ENABLE_MAGLEV=1可与标准 V8 行为进行比较。scripts/run-vitest.mjs会在显式非监视(non-watch)Vitest 运行的已配置无输出截止时间到期时终止该运行。 到期会使运行失败且不会重试该分片,即使子进程以退出码零关闭也是如此。 设置OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=0可在此类有意静默调查中禁用看门狗。scripts/run-tsgo.mjs默认让 tsgo 无界运行,保留现有本地工作流的行为。 将OPENCLAW_TSGO_TIMEOUT_MS设置为正毫秒值,可以让卡死的编译器大声失败,而不是永远阻塞其调用方。 到期时,整个 tsgo 进程树会被杀死,运行失败。高于 Node 计时器上限的值会饱和在该上限, 而不是坍缩为 1ms 截止时间;0、负数、分数或任何高于Number.MAX_SAFE_INTEGER的值都会被拒绝并使运行失败。 环境变量值会先去除首尾空白;剩余值必须使用不带前导零的纯十进制数字,因此1e5或007之类的值会被拒绝。 取消设置该变量可禁用看门狗。 取消编译器分片批次时,会先联接(join)每个编译器进程(需要时包括强制终止), 然后才释放检出工件所有权,以便下一个构建或检查可以继续。
快速本地迭代
pnpm changed:lanes会显示某个 diff 触发了哪些架构泳道。- pre-commit 钩子会格式化文件并重新暂存。配置了私有规则时,它还会在格式化前后扫描暂存内容。 参见 本地提交钩子设置。 它不运行 lint、类型检查或测试。
- 当你需要智能本地检查门禁时,请在交接或推送前显式运行
pnpm check:changed。 pnpm test:changed默认通过低成本的限定泳道路由。仅当代理判断 harness、配置、包或合约修改 确实需要更广泛的 Vitest 覆盖时,才使用OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed。pnpm test:max和pnpm test:changed:max保持相同的路由行为,只是工作线程上限更高。- 本地工作线程自动扩缩容有意保守,当主机负载平均值已经很高时会回退, 因此多个并发 Vitest 运行默认造成的损害较小。 至少拥有 8 个可用 CPU 的 CI 主机可以在 24 到低于 28 GiB 时使用 6 个工作线程, 在 28–128 GiB 时使用 8 个工作线程。已测得的內存配额即使对于两个重型测试进程也保留 25% 的 RAM。 交互式本地大小调整保持不变;显式工作线程覆盖、负载回退、进程内存约束、可用内存压力限制以及 16 个工作线程上限仍然适用。有关测量值和工作流限制,请参阅 CI 工作线程大小调整。
- 基础 Vitest 配置将项目/配置文件标记为
forceRerunTriggers, 以便在测试接线(wiring)更改时,changed 模式下的重跑保持正确。 - 配置在受支持的主机上保持
OPENCLAW_VITEST_FS_MODULE_CACHE启用; 如需一个明确的缓存位置用于直接性能分析,可设置OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path。 - 本地 Node 运行还会复用
.artifacts/vitest-worker-cache中已编译的运行时工作线程输出。 运行器会保留一个检出一地特有的专属输出槽位,并将验证过的工件转移到该槽位。 当其借用方和资源全部 join 之后,它会把已完成的工件转移回缓存,并移除该调用目录。 被占用或不确定的代际永远不会被自动回收。 内容、编译器、配置或解析(resolution)变化会使种子失效;仅时间戳变更不会。 构建来源和资源接收凭证(resource receipts)会在每次调用时刷新, 并且在借出之前和完成之后仍会运行源/输出验证。 在至少有 8 GiB 内存可用时,冷缓存启用的准备工作会与独立的工作线程构建和终结器构建重叠; 内存较小的主机保持顺序编译。 CI 保持新鲜编译,除非其工作流在恢复受保护缓存后启用了OPENCLAW_VITEST_WORKER_CACHE=1。 只有受保护的预热器发布共享代际;普通 CI 作业仍然是远程缓存读取者。 复用要求相同的绝对检出路径和保留输出路径、Node 版本、编译器选项以及验证过的输入。 不兼容或缺失的代际会正常编译。 Bun 和自定义 Node loader 运行保持新鲜编译。 此缓存不会与另一个检出共享 Vitest 的可写文件系统模块缓存。
性能调试
pnpm test:perf:imports启用 Vitest 导入耗时报告以及导入分解输出。pnpm test:perf:imports:changed将相同的性能分析视图限定为自origin/main以来变更的文件。- 分片计时数据写入
.artifacts/vitest-shard-timings.json。整个配置运行使用配置路径作为键;include-pattern CI 分片会附加分片名称,以便可以单独跟踪过滤后的分片。 - 当某个热点测试仍然将大部分时间花在启动导入上时,将重型依赖保留在狭窄的本地
*.runtime.ts接缝后面,并直接模拟该接缝,而不是深度导入运行时辅助工具再通过vi.mock(...)传递它们。 pnpm test:perf:changed:bench -- --ref <git-ref>将路由后的test:changed与该提交差异的原生根项目路径进行比较,并打印墙钟时间以及 macOS 最大 RSS。pnpm test:perf:changed:bench -- --worktree通过将变更文件列表路由到scripts/test-projects.mts和根 Vitest 配置,对当前脏工作树进行基准测试。pnpm test:perf:profile:main写入主线程 CPU 性能分析文件,用于分析 Vitest/Vite 启动和转换开销。pnpm test:perf:profile:runner在禁用文件并行的情况下为单位测试套件写入 runner 的 CPU+堆性能分析文件。性能分析文件覆盖每个 worker 的文件,并在拆卸确认之前完成,包括失败的运行。两个命令都会打印其输出目录;有关输出选择、捕获边界和受支持的 runner,请参阅测试性能工具。
稳定性(网关)¶
- 命令:
pnpm test:stability:gateway - 配置:
test/vitest/vitest.gateway.config.ts、test/vitest/vitest.logging.config.ts和test/vitest/vitest.infra.config.ts,每个均强制使用一个 worker - 范围:
- 启动一个真实的回环 Gateway,默认启用诊断
- 通过诊断事件路径驱动合成的网关消息、内存和大型负载变动
- 通过 Gateway WS RPC 查询
diagnostics.stability - 涵盖诊断稳定性捆绑包持久化辅助工具
- 断言记录器保持有界,合成的 RSS 样本保持在压力预算之下,并且每个会话的队列深度回落到零
- 预期:
- CI 安全且无需密钥
- 用于稳定性回归跟踪的窄通道,不能替代完整的 Gateway 测试套件
E2E(仓库聚合)¶
- 命令:
pnpm test:e2e - 范围:
- 运行网关冒烟 E2E 通道
- 运行模拟 Control UI 浏览器 E2E 通道
- 预期:
- CI 安全且无需密钥
- 需要安装 Playwright Chromium
E2E(网关冒烟测试)¶
- 命令:
pnpm test:e2e:gateway - 配置:
test/vitest/vitest.e2e.config.ts - 文件:
src/**/*.e2e.test.ts、test/**/*.e2e.test.ts以及extensions/下的捆绑插件 E2E 测试 - 运行时默认值:
- 使用 Vitest
threads且isolate: false,与仓库其余部分保持一致。 - 默认使用一个 worker,以保持非隔离网关状态的确定性。
- 默认以静默模式运行,以减少控制台 I/O 开销。
- 有用的覆盖项:
OPENCLAW_E2E_WORKERS=<n>用于选择并行 worker(上限为 16)。OPENCLAW_E2E_VERBOSE=1用于重新启用在控制台的详细输出。- 范围:
- 多实例网关的端到端行为
- WebSocket/HTTP 接口、节点配对以及更重的网络负载
- 预期:
- 在 CI 中运行(当在流水线中启用时)
- 无需真实密钥
- 比单元测试涉及更多变动部分(可能更慢)
E2E(Control UI 模拟浏览器)¶
- 命令:
pnpm test:ui:e2e - 配置:
test/vitest/vitest.ui-e2e.config.ts - 文件:
ui/src/**/*.e2e.test.ts以及 QA Lab 媒体转录真实网关测试套件 - 范围:
- 在两个执行阶段使用四个资源组:
ui-e2e-bundled和ui-e2e-standalone共享并行阶段(总共最多两个 worker);ui-e2e-serial和ui-e2e-serial-standalone共享之后的单 worker 阶段 - 两个使用捆绑包的项目在每次调用时惰性获取一个临时 UI 捆绑包/预览;独立项目拥有自己的夹具、源码或自定义构建服务器
- 仅选择独立测试套件会跳过共享捆绑包构建;新的 E2E 文件默认归捆绑包所有
- 每个被选中的项目都会发现 Chromium 并通过 Playwright 驱动真实页面;根配置保留完整的发现清单
- 大多数测试套件使用确定性的浏览器内模拟替换 Gateway WebSocket;少数会启动隔离的真实网关
- 预期:
- 作为
pnpm test:e2e的一部分在 CI 中运行;资源组不增加 CI 任务 - 无需提供者密钥;
OPENCLAW_UI_E2E_SKIP_REAL_GATEWAY=1排除真实网关测试套件 - 必须存在浏览器依赖(
pnpm --dir ui exec playwright install chromium)
专用的真实网关 CI 通道会在每次干净检出中完成 OPENCLAW_BUILD_PRIVATE_QA=1 OPENCLAW_RUN_NODE_SKIP_DTS_BUILD=1 pnpm build 之后使用 test/vitest/vitest.ui-e2e-prebuilt.config.ts。单独的工件任务保留 SDK 声明验证。规划器将现有的串行文件和选定的独立配套文件平衡在一行中,其余经过审计的并行文件放在另一行中。配套文件在串行执行后共享现有的双 worker 阶段,无需额外的捆绑预览。真实的 node/SSH 桌面调整大小巡览仅限发布:当其文件被完整手动/发布验证或直接编辑 spec 选中时,第一行对所有两个载体运行一次 node --import tsx scripts/test-desktop-resize-real.mts。引导程序仍然是必需的;在没有真实夹具的情况下调用桌面 spec 并非等效证明。频繁的调整大小、撤销、仅查看过滤、接管和 UI 尺寸测试仍保留在普通 CI 中。放置策略使用来自 vitest.ui-paths.mjs 的并行资格允许列表,而不改变 Vitest 调度。每个选中的文件都有一个 CI 所有者;桌面引导程序为每个载体执行一次。完整手动和发布选择保留完整清单。预构建预览借用已验证的规范 Control UI 资源,而无需重建或删除它们;默认的模拟网关 hello 消息使用相同的工件标识,显式模拟标识覆盖仍然适用。普通本地运行保留其私有构建。在所有 worker 和子进程完成之前,保持源码和构建输出不变。夹具保留其私有 HOME、状态、端口、清理和现有 worker 限制。就绪失败会停止,而不会重建或回退。普通本地配置保持真实网关文件为串行;冻结的目标和较旧的规划器保留一个完整的 CI 行及其自己的配置/命令。有关资源策略和计时的证据,请参阅 CI。
网络隔离的本地 E2E¶
当 Chromium 可用时,UI E2E 设置会在获取 Gateway 夹具或共享 UI 构建之前,通过父 Node 进程的常规 fetch 验证回环 HTTP。代理拒绝或格式错误的响应会使该环境预检以脱敏错误失败,而不是消耗 Gateway 启动预算。现有的可选缺失浏览器跳过保持不变。如果之后 Gateway 就绪状态过期,其错误也会保留最后一次已完成的 HTTP 失败,以便最终截止边缘超时不会隐藏有用的状态和错误类别证据。
由 Gateway 承载的 exec 可以继承 secret egress 代理。其纯 HTTP 拒绝也适用于调用自身回环夹具的测试进程。因此,Gateway 可以记录其已就绪,而其父进程从 /readyz 收到代理错误。重新构建 UI 或增加就绪超时时间都无法修复该传输不匹配。
对于受信任的、无密钥的本地测试,请改为在隔离的 Linux 容器中运行完整调用。通过完整镜像 ID 或摘要选择已准备好的受信任镜像;运行器从不拉取镜像,也不回退到主机:
node scripts/run-vitest.mjs --isolated-image "$IMAGE_ID" run \
--config test/vitest/vitest.ui-e2e.config.ts --configLoader runner \
ui/src/e2e/command-palette-catalog.real-gateway.e2e.test.ts
该适配器要求 Linux、一个现有的 rootless Podman 安装及其原生 init 辅助程序(通常为 catatonit)、检出本地的 pnpm install --frozen-lockfile 依赖项,以及与镜像兼容的原生 Node 和 pnpm 可执行文件。将匹配 package.json 的原生 pnpm 可执行文件放到 PATH 中,或通过现有的 npm_execpath 环境变量选择它;Corepack/下载 shim 不是离线可执行文件。镜像必须已经包含已安装的 Playwright 包在 /ms-playwright 下所需的 Chromium 修订版本,包括其 headless shell 和系统库。运行器在启动测试命令之前会检查版本并启动 Chromium。带有 SELinux 标签的主机不受此初始适配器支持:它会在创建容器之前拒绝,而不是重新标记共享主机文件或禁用强制模式。请使用已支持的隔离运行器,而不是更改主机安全策略。
它在同一个 network-none 命名空间中运行 Vitest、Chromium、provider 夹具和测试 Gateway。Podman 的 init 拥有 PID 1,因此分离的测试子进程会在其启动器退出后被回收;Node 入口点仍然拥有测试调用和清理。主机代理设置保持不变;主机凭据、Gateway 状态、Git 元数据和私有临时文件不会暴露给容器。没有发布端口或外部网络访问。缺少前置条件时会以设置指导失败,而不是安装软件包或削弱隔离。
使用普通本地配置,而不是仅限 CI 的预构建配置。该适配器使用规范测试选择,在容器内为消费已构建运行时的测试准备 qaRuntime 工件,包括需要时的 private-QA 工件。仅源码选择不会承担运行时构建成本,并保留 8 GiB 容器内存上限。准备已构建工件的运行使用有界的 16 GiB 上限,以适应编译器堆和原生构建内存;CPU、网络、文件系统和进程限制保持不变。对于规范的 Control UI E2E 配置,它在允许测试之前保留 private-QA ciArtifacts 构建;仅后端就绪并不意味着仪表板资源已就绪。主机的实时 Gateway 工件准入保持不变。隔离的源码快照使用受跟踪的工作树文件,包括已暂存的新文件;在选择新测试之前先暂存它。在调用期间保持源码和依赖项不变,并将依赖项安装分开。初始接口支持精确的受跟踪测试文件、受跟踪的配置和控制台报告器;它不会从一次性快照中导出文件。此路径不适用于实时 provider 测试或必须联系其自身容器外部服务的测试。
E2E:OpenShell 后端冒烟¶
- 命令:
pnpm test:e2e:openshell - 文件:
extensions/openshell/src/backend.e2e.test.ts - 范围:
- 复用活动的本地 OpenShell gateway
- 从临时本地 Dockerfile 创建沙箱
- 通过真实 SSH 验证远程和默认镜像 OpenShell 后端
- 创建隔离的非默认 OpenShell 工作区和自定义工作区根目录
- 验证嵌套镜像文件写入,并排除主机 Git 元数据和 hooks
- 通过沙箱 fs 桥验证远程规范文件系统行为
- 预期:
- 仅可选启用;不属于默认
pnpm test:e2e运行 - 需要本地
openshellCLI 以及可用的 Docker 守护进程 - 需要活动的本地 OpenShell gateway 及其配置源
- 使用隔离的
HOME/XDG_CONFIG_HOME,然后在删除测试工作区之前等待沙箱持久缺失 - 报告清理失败,包括失败的清单查询;它不会重试数据库错误
- 有用的覆盖:
OPENCLAW_E2E_OPENSHELL=1在手动运行更广泛的 e2e 套件时启用测试OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell指向非默认 CLI 二进制文件或包装脚本OPENCLAW_E2E_OPENSHELL_CONFIG_HOME=/path/to/config向隔离测试暴露已注册的 gateway 配置OPENCLAW_E2E_OPENSHELL_HOST_IP=172.18.0.1用显式 Docker gateway 地址及其现有/32后缀替换主机策略夹具的默认范围
实时(真实 provider + 真实模型)¶
- 命令:
pnpm test:live - 配置:
test/vitest/vitest.live.config.ts - 文件:
src/**/*.live.test.ts、test/**/*.live.test.ts,以及extensions/下的捆绑插件 live 测试 - 默认:由
pnpm test:live启用(设置OPENCLAW_LIVE_TEST=1) - 运行时:默认 Node;
OPENCLAW_VITEST_RUNTIME=bun pnpm test:live为 Vitest 及其 worker 选择PATH上的 Bun 可执行文件,使用与 CI 测试通道相同的运行时选择器。live 包装器仍在 Node 上运行。 - 范围:
- “这个 provider/模型在 今天 使用真实凭据是否真的可用?”
- 捕获 provider 格式变化、工具调用怪癖、认证问题和速率限制行为
- 预期:
- 设计上不保证 CI 稳定(真实网络、真实 provider 策略、配额、故障)
- 花费金钱 / 使用速率限制
- 优先运行缩小范围,而不是“全部”
- live 运行使用已导出的 API 密钥和已暂存的认证配置。
- 默认情况下,live 运行仍会隔离
HOME,并将配置/认证材料复制到临时测试主目录,因此单元测试夹具无法修改你真实的~/.openclaw。 - 仅当你有意需要 live 测试使用真实主目录时,才设置
OPENCLAW_LIVE_USE_REAL_HOME=1。 pnpm test:live默认使用更安静的模式:它保留[live] ...进度输出,并静音 gateway 引导日志/Bonjour 噪音。如果你希望恢复完整启动日志,请设置OPENCLAW_LIVE_TEST_QUIET=0。- API 密钥轮换(特定 provider):以逗号/分号格式设置
*_API_KEYS,或设置*_API_KEY_1、*_API_KEY_2(例如OPENAI_API_KEYS、ANTHROPIC_API_KEYS、GEMINI_API_KEYS),或通过OPENCLAW_LIVE_*_KEY进行每次 live 覆盖;测试会在速率限制响应上重试。 - 进度/心跳输出:
- live 套件向 stderr 输出进度行,因此即使 Vitest 控制台捕获安静,长时间 provider 调用也可见为活动状态。
test/vitest/vitest.live.config.ts禁用 Vitest 控制台拦截,以便在 live 运行期间 provider/gateway 进度行立即流式输出。- 使用
OPENCLAW_LIVE_HEARTBEAT_MS调整直接模型心跳。 - 使用
OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS调整 gateway/检查心跳。
建议性 Bun 发布检查¶
维护者可以在 main 上以 test_runtime=bun 触发 openclaw-live-and-e2e-checks-reusable.yml。手动输入提供 node 和 bun;可复用调用方接受相同的字符串值。Node 仍然是默认值,包括现有的 Release Checks 和 Full Release Validation 调用方。
可复用 Bun 调用方必须使用与被调用工作流相同的仓库和修订版本,以便固定版本来自该确切的工作流源。直接触发会自动满足此要求。
对于常规稳定发布仓库/实时选择:
target_sha="$(gh api repos/openclaw/openclaw/commits/main --jq .sha)"
gh workflow run openclaw-live-and-e2e-checks-reusable.yml --ref main \
-f ref="$target_sha" -f test_runtime=bun -f release_test_profile=stable \
-f include_repo_e2e=true -f include_live_suites=true \
-f include_release_path_suites=false -f include_openwebui=false \
-f gateway_repo_e2e_use_github_hosted_runners=false \
-f allow_unreleased_changelog=true
Bun 作业被标记为建议性,并在其独立运行中正常报告失败。它们不会替代 Node 发布证据,也不会添加 PR 作业。受信任的准入检出包括来自工作流修订版本的 scripts/lib/openclaw-bun.json 及其暂存辅助文件。现有的 setup-test-bun 操作会安装一次该固定版本,并通过工件 ID 与测试作业共享其可执行文件。
只有测试步骤选择 Bun;依赖安装、构建准备、打包和工作流工具保持当前工具链。
该选择器覆盖原生实时分片、实时缓存检查、Gateway 分片、agent-plugin Gateway、完整的 UI E2E 套件(包括 real-Gateway 文件)以及 OpenShell Vitest 主机。当由 full 配置文件选择时,原生媒体分片支持相同的选择器。独立的必需 PR CI real-Gateway 作业仍由其现有运行时策略管理,不属于此发布通道。
Docker live/model、打包产品、升级和 OpenWebUI 通道保留 Node:它们的镜像和启动器拥有容器运行时,因此主机 Vitest 选择器不会切换它们。外部提供商 CLI 和 OpenShell 服务也保留其自己的运行时。这些通道在被选择时仍会运行,但不是 Bun 验证。 使用包含运行时感知的实时和 E2E 启动器的当前目标;较旧的冻结发布目标可能不支持此建议性选择器。
我应该运行哪个测试套件?¶
使用此决策表:
- 编辑逻辑/测试:运行
pnpm test(如果你更改了很多,则运行pnpm test:coverage) - 触及 gateway 网络 / WS 协议 / 配对:添加
pnpm test:e2e - 调试“我的机器人宕机了” / 特定提供商故障 / 工具调用:运行一个收窄的
pnpm test:live
实时(涉及网络)测试¶
对于实时模型矩阵、CLI 后端冒烟测试、ACP 冒烟测试、Codex app-server 测试框架,以及所有媒体提供商实时测试(Deepgram、BytePlus、ComfyUI、图像、音乐、视频、媒体测试框架)——加上实时运行的凭据处理
文档健全性检查¶
在文档编辑后运行文档检查:pnpm check:docs。
当你还需要页面内标题检查时,运行共享发布解析器的锚点审计:pnpm docs:check-links:anchors。
当无法获得可靠的源行时,诊断显示 unknown。
离线回归(CI 安全)¶
这些是“真实流水线”回归,但不使用真实提供商:
- Gateway 代理准入(使用模拟 OpenAI 提供商的真实 Gateway):
src/gateway/gateway.test.ts(用例:“accepts a gateway agent request over ws and returns a run id”;检查接受、运行 ID 和中止响应)。 - Gateway 向导(WS
wizard.start/wizard.next,写入配置 + 强制身份验证):src/gateway/gateway.test.ts(用例:“runs wizard over ws and writes auth token config”)
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw