跳转至

测试套件和命令

快速开始

大多数日子：

  • 完整门禁（推送前预期执行）：pnpm build && pnpm check && pnpm check:test-types && pnpm test
  • 在配置充裕的机器上更快地本地运行完整套件：pnpm test:max
  • 直接使用 Vitest 监听循环：pnpm test:watch
  • 直接文件定位同样会路由插件/通道路径：pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
  • 当针对单个失败进行迭代时，优先使用定向运行。
  • 基于 Docker 的 QA 站点：pnpm qa:lab:up
  • 基于 Linux 虚拟机的 QA 通道：pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

最后两条通道需要其他命令不需要的工具：qa:lab:up 需要 运行中的 Docker 守护进程和源码检出，因为 npm 压缩包不包含 QA Lab，而 multipass 运行器需要安装 Multipass。请参阅 QA 专用运行器。

当你改动测试或希望获得额外信心时：

  • 参考性 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 分片中运行
  • 范围：
  • 纯单元测试
  • 进程内集成测试（网关认证、路由、工具、解析、配置）
  • 针对已知问题的确定性回归测试
  • 预期：
  • 在 CI 中运行
  • 无需真实密钥
  • 应快速且稳定
  • 解析器和公共表面加载器测试必须使用生成的小型插件夹具来证明 api.js 和 runtime-api.js 的广泛回退行为，而不是使用真实打包的插件源码 API。真实的插件 API 加载属于插件自有的契约/集成测试套件。

原生依赖策略：

  • 默认测试安装会跳过可选的本地 Discord opus 构建。Discord 语音使用捆绑的 libopus-wasm，并且 @discordjs/opus 在 allowBuilds 中保持禁用，这样本地测试和 Testbox 通道就不会编译原生插件。
  • 请在 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 可避免承担完整的根项目启动开销。
  • 非监听模式下的包目录目标（如 pnpm test packages 或 pnpm test packages/gateway-client）会查找常规的 *.test.ts 文件，并将每个文件路由到其所属通道，同时保留共享排除规则和继承的包含限制。
  • 非监听模式的根项目运行（如 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 分类为核心、核心测试、扩展、扩展测试、应用、文档、发布元数据、实时 Docker 工具和工具，然后运行匹配的类型检查、lint 和守卫命令。所选路径还会通过 pnpm test:serial 调度定向的 Vitest 所有者测试；如需与所改动契约匹配的额外测试证明，可使用 pnpm test:changed 或显式 pnpm test <target>。仅发布元数据的版本号提升会运行定向的版本/配置/根依赖检查，并有一个守卫会拒绝顶级版本字段之外的包变更。
  • 在默认针对 HEAD 的 Git diff 模式下，仅注释/空白变更的 TypeScript 编辑，如果 token 和换行边界与合并基线一致，会跳过其类型检查通道和核心图边界检查。包含 TypeScript/JSX 指令、三斜线注释、解析错误或路径生命周期变更的文件仍需类型检查，JavaScript 文件同样如此。Lint、格式化、棘轮、守卫和测试保留完整的变更路径范围。暂存、显式路径和非 HEAD 比较保留正常的类型检查选择；--dry-run 会报告任何被跳过的路径。
  • 实时 Docker ACP 工具集的编辑会运行针对性检查：实时 Docker 认证脚本的 shell 语法检查，以及实时 Docker 调度器的试运行。package.json 变更仅在 diff 限于 scripts["test:docker:live-*"] 时才会被纳入；依赖、导出、版本和其他包表面修改仍使用更广泛的守卫。
  • 来自 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 会特意跳过捆绑插件批量扫描和仅发布用的 agentic-plugins 分片。完整发布验证会在候选版本上为这些插件密集型套件调度单独的 Plugin Prerelease 子工作流。
嵌入式运行器覆盖
  • 当你更改 message-tool 发现输入或压缩运行时上下文时，请保持两层覆盖。
  • 为纯路由和规范化边界添加有针对性的辅助回归测试。
  • 保持嵌入式运行器集成套件健康运行： 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。工作进程数量和 文件并行度保持不变。
  • 共享 Vitest 配置固定为 isolate: false，并在根项目、e2e 和 live 配置中 统一使用非隔离运行器。
  • 根 UI lane 保留其 jsdom 设置和优化器，但也在共享的非隔离运行器上运行。
  • Provider 插件分片通过共享清理运行器复用工作进程。使用 vi.stubGlobal 跟踪全局替换，以便清理操作能在下一个文件之前恢复它们。
  • 在每次测试尝试之前以及文件的清理之前，共享运行器会等待先前 teardown 未等待 就安排的 agent 数据库关闭，因此 Worker 租约释放永远不会与下一个测试重叠。 失败的关闭仍归属于其所有者，并在文件末尾排空时一并处理，与之前一致。
  • 每个 pnpm test 分片都继承共享 Vitest 配置中的平台池和 isolate: false 默认值，除非其所有者另行选择。
  • scripts/run-vitest.mjs 默认会为 Vitest 子 Node 进程添加 --no-maglev， 以减少大型本地运行期间 V8 的编译波动。设置 OPENCLAW_VITEST_ENABLE_MAGLEV=1 可与标准 V8 行为进行对比。
  • scripts/run-vitest.mjs 会在配置的无输出截止时间到期时终止显式的非 watch Vitest 运行。到期会使运行失败且不会重试该分片，即使子进程以退出码 0 关闭 也是如此。设置 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 每个编译器（必要时包括强制终止），然后 才释放 checkout 产物所有权，以便下一个构建或检查可以继续进行。
快速本地迭代
  • pnpm changed:lanes 显示 diff 触发了哪些架构 lane。
  • pre-commit 钩子会格式化文件并重新暂存。当配置了私有规则时，它还会在格式化 前后扫描暂存内容。参见 本地提交钩子设置。 它不会运行 lint、typecheck 或测试。
  • 当你需要智能本地检查门禁时，请在移交或推送前显式运行 pnpm check:changed。
  • pnpm test:changed 默认通过开销较低的限定 lane 路由。仅在 agent 判定 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 配置将 projects/config 文件标记为 forceRerunTriggers， 因此当测试接线变更时，changed-mode 重跑仍能保持正确。
  • 该配置在受支持的主机上保持启用 OPENCLAW_VITEST_FS_MODULE_CACHE； 设置 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path 可指定一个显式 缓存位置用于直接性能分析。
  • 本地 Node 运行还会复用来自 .artifacts/vitest-worker-cache 的已编译 运行时工作进程产物。运行器会保留一个独占的 checkout 本地输出槽位，并将 验证过的产物转移到该槽位。在其借用方和资源 join 之后，它会将完成的产物 转移回缓存，并移除调用目录。被占用或状态不确定的世代永远不会被自动回收。 内容、编译器、配置或解析变更会使种子失效；仅时间戳变动不会。构建出处和 资源凭证会在每次调用时刷新，并且源/输出验证在出借前和完成后仍会运行。 当至少 8 GiB 内存可用时，启用冷缓存的准备会与独立的工作进程和 finalizer 构建重叠；内存较小的主机保持顺序编译。CI 保持全新编译，除非其工作流在恢复 受保护缓存后启用 OPENCLAW_VITEST_WORKER_CACHE=1。只有受保护的预热器会 发布共享世代；普通 CI 任务仍是远程缓存读取者。复用要求相同的绝对 checkout 路径和预留输出路径、Node 版本、编译器选项以及已验证的输入。不兼容或缺失的 世代会正常编译。Bun 和自定义 Node loader 运行保持全新编译。此缓存不会与 另一个 checkout 共享 Vitest 的可写文件系统模块缓存。
性能调试
  • pnpm test:perf:imports 启用 Vitest 导入耗时报告以及 导入分解输出。
  • pnpm test:perf:imports:changed 将相同的性能分析视图限定为 自 origin/main 以来发生更改的文件。
  • 分片计时数据写入 .artifacts/vitest-shard-timings.json。 整个配置的运行使用配置路径作为键；包含模式 CI 分片会追加分片名称，以便单独跟踪过滤后的分片。
  • 当某个热点测试仍将大部分时间花在启动导入上时， 请将重量级依赖保留在狭窄的本地 *.runtime.ts 接缝后面， 并直接 mock 该接缝，而不是深度导入运行时辅助函数 仅为将它们通过 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 为 Vitest/Vite 启动和转换开销写入主线程 CPU 配置文件。
  • pnpm test:perf:profile:runner 为 单元测试套件写入 runner CPU+heap 配置文件，并禁用文件并行。配置文件涵盖每个 worker 的 文件，并在 teardown 确认之前结束，包括失败运行。 两个命令都会打印其输出目录；请参阅 测试性能工具 了解输出选择、捕获边界和受支持的 runner。

稳定性（网关）

  • 命令：pnpm test:stability:gateway
  • 配置：test/vitest/vitest.gateway.config.ts、test/vitest/vitest.logging.config.ts 和 test/vitest/vitest.infra.config.ts，每个都强制使用一个 worker
  • 范围：
  • 默认启用诊断，启动一个真实的 loopback Gateway
  • 通过诊断事件路径驱动合成的 gateway 消息、内存和大负载变化
  • 通过 Gateway WS RPC 查询 diagnostics.stability
  • 覆盖诊断稳定性 bundle 持久化辅助函数
  • 断言 recorder 保持有界，合成 RSS 样本保持在压力预算之下，并且每个会话的队列深度排空回零
  • 预期：
  • CI 安全且无需密钥
  • 用于稳定性回归跟进的狭窄通道，不是完整 Gateway 套件的替代品

E2E（仓库聚合）

  • 命令：pnpm test:e2e
  • 范围：
  • 运行 gateway smoke E2E 通道
  • 运行 mocked Control UI 浏览器 E2E 通道
  • 预期：
  • CI 安全且无需密钥
  • 需要安装 Playwright Chromium

E2E（gateway smoke）

  • 命令：pnpm test:e2e:gateway
  • 配置：test/vitest/vitest.e2e.config.ts
  • 文件：src/**/*.e2e.test.ts、test/**/*.e2e.test.ts，以及 extensions/ 下的 bundled-plugin E2E 测试
  • 运行时默认值：
  • 使用 Vitest threads 并设置 isolate: false，与仓库其余部分保持一致。
  • 默认使用一个 worker，以保持非隔离 gateway 状态确定性。
  • 默认以静默模式运行，以减少控制台 I/O 开销。
  • 常用覆盖项：
  • OPENCLAW_E2E_WORKERS=<n> 用于选择启用并行 worker（上限为 16）。
  • OPENCLAW_E2E_VERBOSE=1 用于重新启用详细控制台输出。
  • 范围：
  • 多实例 gateway 端到端行为
  • WebSocket/HTTP 表面、节点配对和更重的网络
  • 预期：
  • 在 CI 中运行（当在流水线中启用时）
  • 不需要真实密钥
  • 比单元测试有更多活动部件（可能更慢）

E2E（Control UI mocked 浏览器）

  • 命令：pnpm test:ui:e2e
  • 配置：test/vitest/vitest.ui-e2e.config.ts
  • 文件：ui/src/**/*.e2e.test.ts 以及 QA Lab media-transcript real-Gateway 套件
  • 范围：
  • 在两个执行阶段中使用四个资源组：ui-e2e-bundled 和 ui-e2e-standalone 共享并行阶段（总共最多两个 worker）；ui-e2e-serial 和 ui-e2e-serial-standalone 共享后面的单 worker 阶段
  • 两个 bundle-consuming 项目每次调用时懒加载获取一个临时 UI bundle/preview；standalone 项目拥有自己的 fixture、source 或自定义构建服务器
  • 仅选择 standalone 套件会跳过共享 bundle 构建；新的 E2E 文件默认使用 bundled 所有权
  • 每个选中的项目都会发现 Chromium 并通过 Playwright 驱动真实页面；根配置保留完整的发现清单
  • 大多数套件用确定性的浏览器内 mock 替换 Gateway WebSocket；一些套件启动隔离的真实 Gateway
  • 预期：
  • 作为 pnpm test:e2e 的一部分在 CI 中运行；资源组不会增加 CI 任务
  • 不需要 provider 密钥；OPENCLAW_UI_E2E_SKIP_REAL_GATEWAY=1 排除 real-Gateway 套件
  • 必须存在浏览器依赖（pnpm --dir ui exec playwright install chromium）

专用的 real-Gateway CI 通道在每个干净检出中，OPENCLAW_BUILD_PRIVATE_QA=1 OPENCLAW_RUN_NODE_SKIP_DTS_BUILD=1 pnpm build 完成后使用 test/vitest/vitest.ui-e2e-prebuilt.config.ts。独立的 artifact 任务保留 SDK 声明验证。规划器将现有 serial 文件和选中的 standalone 伴随文件平衡在一行中，其余经过审计的 parallel 文件在另一行中。伴随文件在 serial 执行后共享现有的双 worker 阶段，而不需要额外的 bundled preview。真实的 node/SSH 桌面 resize 之旅仅用于 release：当它的文件被完整 manual/release 验证或直接 spec 编辑选中时，第一行对两个 carrier 运行一次 node --import tsx scripts/test-desktop-resize-real.mts。bootstrap 仍然必需；在没有其真实 fixture 的情况下调用 desktop spec 不构成等效证明。频繁的 resize、吊销、仅查看过滤、接管和 UI 尺寸测试保留在普通 CI 中。放置从 vitest.ui-paths.mjs 消费 parallel-eligibility 允许列表，而不改变 Vitest 调度。每个选中的文件有一个 CI owner；desktop bootstrap 对每个 carrier 执行一次。完整 manual 和 release 选择保留完整清单。预构建 preview 借用已验证的规范 Control UI 资产，而不重建或删除它们；默认 mocked Gateway hellos 使用相同的 artifact 标识，并且显式 mock 标识覆盖仍然适用。普通本地运行保留其私有构建。在所有 worker 和子进程完成之前，保持 source 和构建输出不变。fixture 保留其私有 HOME、状态、端口、清理和现有 worker 限制。就绪失败会停止，而不重建或回退。普通本地配置保持 real-Gateway 文件 serial；冻结目标和旧规划器保留一个完整 CI 行及其自己的 config/command。请参阅 CI 了解资源策略和计时证据。

网络隔离的本地 E2E

当 Chromium 可用时，UI E2E 设置会在获取 Gateway 夹具或共享 UI 构建之前，通过父 Node 进程的常规 fetch 验证回环 HTTP。代理拒绝或格式错误的响应会使该环境预检以脱敏错误失败，而不是消耗 Gateway 启动预算。现有的可选缺失浏览器跳过行为保持不变。如果稍后 Gateway 就绪状态过期，其错误也会保留最后一次已完成的 HTTP 失败，以便最终的截止时间边缘超时不会掩盖有用的状态和错误类别证据。

Gateway 托管的 exec 可以继承 secret egress proxy。其对纯 HTTP 的拒绝也适用于测试进程调用自身回环夹具的情况。因此，Gateway 可以记录自身已就绪，而其父进程却从 /readyz 收到代理错误。重新构建 UI 或增加就绪超时都无法修复该传输不匹配。

对于受信任的、无密钥的本地测试，请改为在隔离的 Linux 容器中运行完整调用。通过完整镜像 ID 或摘要选择已准备好的受信任镜像；runner 从不拉取镜像，也不会回退到主机：

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 修订版本，包括其无头 shell 和系统库。runner 会在启动测试命令之前检查版本并启动 Chromium。此初始适配器不支持带 SELinux 标签的主机：它会在创建容器之前拒绝，而不是重新标记共享主机文件或禁用强制模式。请使用已支持的隔离 runner，而不是更改主机安全策略。

它在同一个 network-none 命名空间中运行 Vitest、Chromium、provider 夹具和测试 Gateway。Podman 的 init 拥有 PID 1，因此分离的测试子进程会在其启动器退出后被回收；Node 入口点仍然负责测试调用和清理。主机代理设置保持不变；主机凭据、Gateway 状态、Git 元数据和私有临时目录不会暴露给容器。没有发布端口或外部网络访问。缺失的前置条件会附带设置指导而失败，而不是安装软件包或削弱隔离。

请使用普通本地配置，而不是仅用于 CI 的预构建配置。对于规范的 Control UI E2E 配置，适配器会在容器内运行现有的 private-QA ciArtifacts 构建，然后才允许测试进入；仅后端就绪并不意味着 dashboard 资源已就绪。隔离源快照使用受跟踪的工作树文件，包括已暂存的新文件；在选择新测试之前先暂存它。在调用期间保持源代码和依赖不变，并将依赖安装分开。初始接口支持精确的受跟踪测试文件、受跟踪配置和控制台报告器；它不会从一次性快照中导出文件。此路径不适合实时提供商测试，也不适合必须联系自身容器外部服务的测试。

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 运行
  • 需要本地 openshell CLI 以及可工作的 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 后缀替换主机策略夹具的默认范围

实时测试（真实提供商 + 真实模型）

  • 命令：pnpm test:live
  • 配置：test/vitest/vitest.live.config.ts
  • 文件：src/**/*.live.test.ts、test/**/*.live.test.ts，以及 extensions/ 下的捆绑插件实时测试
  • 默认：由 pnpm test:live 启用（设置 OPENCLAW_LIVE_TEST=1）
  • 范围：
  • “这个提供商/模型在 今天 使用真实凭据是否真的可用？”
  • 捕获提供商格式变化、工具调用怪癖、认证问题和速率限制行为
  • 预期：
  • 设计上不是 CI 稳定的（真实网络、真实提供商策略、配额、故障）
  • 会产生费用 / 使用速率限制
  • 建议运行收窄的子集，而不是“全部”
  • 实时运行使用已导出的 API 密钥和已暂存的认证配置。
  • 默认情况下，实时运行仍会隔离 HOME，并将配置/认证材料复制到临时测试主目录，以便单元测试夹具无法修改你的真实 ~/.openclaw。
  • 仅当你确实需要实时测试使用你的真实主目录时，才设置 OPENCLAW_LIVE_USE_REAL_HOME=1。
  • pnpm test:live 默认使用更安静的模式：它保留 [live] ... 进度输出，并静音 gateway 引导日志/Bonjour 噪音。如果你希望恢复完整启动日志，请设置 OPENCLAW_LIVE_TEST_QUIET=0。
  • API 密钥轮换（特定提供商）：以逗号/分号格式设置 *_API_KEYS，或设置 *_API_KEY_1、*_API_KEY_2（例如 OPENAI_API_KEYS、ANTHROPIC_API_KEYS、GEMINI_API_KEYS），或通过 OPENCLAW_LIVE_*_KEY 进行按实时运行的覆盖；测试会在速率限制响应上重试。
  • 进度/心跳输出：
  • 实时套件会将进度行输出到 stderr，以便即使 Vitest 控制台捕获处于安静状态，长时间提供商调用也可见为活动状态。
  • test/vitest/vitest.live.config.ts 禁用 Vitest 控制台拦截，以便在实时运行期间提供商/gateway 进度行立即流式输出。
  • 使用 OPENCLAW_LIVE_HEARTBEAT_MS 调整直接模型心跳。
  • 使用 OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS 调整 gateway/探测心跳。

我该运行哪个测试套件？

使用以下决策表：

  • 编辑逻辑/测试：运行 pnpm test（如果改动较多，再运行 pnpm test:coverage）
  • 涉及网关网络 / 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 安全）

这些是“真实流水线”回归测试，但不使用真实提供商：

  • 网关代理准入（使用模拟 OpenAI 提供商的真实 Gateway）：src/gateway/gateway.test.ts（用例："accepts a gateway agent request over ws and returns a run id"；检查接受、运行 ID 和中断响应）。
  • 网关向导（WS wizard.start/wizard.next，写入配置并强制认证）：src/gateway/gateway.test.ts（用例："runs wizard over ws and writes auth token config"）

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