--- read_when: - 运行或修复测试 summary: 如何在本地运行测试（vitest），以及何时使用强制/覆盖率模式 title: 测试 x-i18n: generated_at: "2026-07-14T14:06:13Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 25 provider: openai source_hash: 391185703e853bb523e1396eb22da4693d10d47b1644d3b2a51707d329f67dae source_path: reference/test.md workflow: 16 --- - 完整测试工具包（测试套件、实时测试、Docker）：[测试](/zh-CN/help/testing) - 更新和插件包验证：[更新和插件测试](/zh-CN/help/testing-updates-plugins) ## Agent 默认行为 仅当源代码可信且现有依赖安装已就绪时，Agent 会话才在本地运行少量有针对性的测试和成本较低的静态检查。绝不要在本地执行不受信任的仓库工具。较大的测试套件、包含类型检查/代码检查扇出的变更门禁、构建、Docker、软件包通道、E2E、实时验证和跨平台验证均通过 Crabbox 远程运行。受信任维护者的重型验证默认使用 Blacksmith Testbox。配置的 Testbox 工作流会注入凭据，因此不受信任的贡献者代码或分支代码必须改用无密钥的分支 CI 或经过净化的 AWS 直连 Crabbox。 不要为预期的工作预热。当第一个重型命令准备就绪时再按需获取后端，后续重型命令复用返回的 `tbx_...` ID，每次运行时同步当前检出，并在交接前停止后端。 首次成功复用后，包装器会将租约的基线、依赖项和 Testbox 工作流指纹记录在 `.crabbox/testbox-leases/` 下。仅修改源代码时会继续复用已预热的机器。合并基线、锁文件、包管理器输入、包装器或 Testbox 工作流发生变化时，会以失败关闭方式中止，并要求使用新租约。每次运行仍会同步当前检出。 `OPENCLAW_TESTBOX_ALLOW_STALE=1` 仅用于有意进行的诊断，不得用于发布验证。 以下本地测试命令适用于人工工作流和有限范围的 Agent 验证。必须报告远程提供商不可用的情况；这并不意味着可以静默运行大范围的本地门禁。 对于不受信任的重型验证，请使用 `--provider aws` 按需预热。每次运行都必须设置 `CRABBOX_ENV_ALLOW=CI`、传入 `--provider aws --no-hydrate`，并在安装依赖项或运行测试前使用一个全新的临时远程 `HOME`。使用专用于该不受信任源代码的新预热租约；绝不要复用受信任的租约或先前已注入凭据的租约。从干净且受信任的 `main` 检出中启动已安装且受信任的 Crabbox 二进制文件，并仅使用 `--fresh-pr` 获取远程 PR；绝不要在本地执行不受信任检出中的包装器或配置。取消设置 `CRABBOX_AWS_INSTANCE_PROFILE`，除非解析出的 `aws.instanceProfile` 为空，否则以失败关闭方式中止。在进行任何安装/测试之前，使用受信任的绝对路径工具要求提供 IMDSv2 令牌，证明 IAM 凭据端点返回 404，并验证远程 `git rev-parse HEAD` 等于已审核 PR 头部的完整 SHA。将租约绑定到该 SHA，并在头部发生变化时停止租约并重新预热。将干净 `main` 中受信任的 `scripts/crabbox-untrusted-bootstrap.sh` 与 `--fresh-pr` 一同上传；它会安装固定版本的 Node/pnpm、验证 SHA 和包管理器版本锁定、隔离 `HOME`、安装依赖项，然后执行所请求的测试。如果代理程序无法证明不存在角色，或远程 PR 不存在，请使用无密钥的分支 CI。不要使用 `hydrate-github`、`--no-sync` 或注入了凭据的 Testbox 工作流。 取消设置所有 `CRABBOX_TAILSCALE*` 覆盖项，强制使用 `--network public --tailscale=false`，清除出口节点/LAN 标志，并要求 `crabbox inspect` 在上传任何脚本之前报告使用公共网络且不存在 Tailscale 状态。 ## 常规本地顺序 1. `pnpm test:changed` 用于变更范围的 Vitest 验证。 2. `pnpm test ` 用于单个文件、目录或显式目标。 3. 仅当你有意需要完整的本地 Vitest 测试套件时，才使用 `pnpm test`。 在 Codex 工作树或链接/稀疏检出中，智能体应避免直接在本地运行 `pnpm test*` / `pnpm check*` / `pnpm crabbox:run`： - 依赖项已就绪时的有界聚焦验证： `node scripts/run-vitest.mjs `。 - 优先分类的变更检查：`node scripts/check-changed.mjs`；仅文档、 无变更和小型元数据计划在依赖项已就绪时留在本地执行， 而繁重或缺少依赖项的计划则委派给 Testbox。 - 显式保留租约的广泛验证：`node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed`，使 pnpm 在 Testbox 内运行。 - 包装器最终的 `exitCode` 和计时 JSON 即为命令结果。委派的 Blacksmith GitHub Actions 运行可能会在 SSH 命令成功后显示 `cancelled`，因为 Testbox 是从保活 action 外部停止的；在将其视为失败之前，请检查包装器摘要和命令输出。 - `OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree `：对于 `pnpm check:changed` 和定向 `pnpm test ...` 等命令，将繁重检查的串行化保持在当前工作树内，而不是 Git 公共目录内。仅当你有意在高性能本地主机上跨链接工作树运行相互独立的检查时使用它。 ## 核心命令 测试包装器运行结束时会显示简短的 `[test] passed|failed|skipped ... in ...` 摘要；Vitest 自身的耗时行仍作为每个分片的详细信息。 | 命令 | 作用 | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | 显式文件/目录目标通过限定范围的 Vitest 通道运行。无目标运行属于完整测试套件验证：固定分片组会展开为叶级配置，以便在本地并行执行，并在开始前输出预期的分片扇出。扩展组始终展开为逐扩展分片配置，而不是使用一个庞大的根项目进程。 | | `pnpm test:changed` | 低成本的智能变更测试运行：根据直接测试编辑、同级 `*.test.ts` 文件、显式源映射和本地导入图确定精确目标。除非广泛变更、配置变更或软件包变更能够映射到精确测试，否则将跳过这些变更。 | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | 显式的广泛变更测试运行；当测试工具、配置或软件包编辑应回退到 Vitest 更广泛的变更测试行为时使用。 | | `pnpm test:force` | 释放已配置的 OpenClaw Gateway 网关端口（默认值为 `18789`），然后使用隔离的 Gateway 网关端口运行完整测试套件，使服务器测试不会与正在运行的实例冲突。 | | `pnpm test:coverage` | 为默认单元测试通道（`vitest.unit.config.ts`）生成信息性 V8 覆盖率报告；不强制执行覆盖率阈值。 | | `pnpm test:coverage:changed` | 仅对自 `origin/main` 起发生变更的文件进行单元测试覆盖率检查。 | | `pnpm changed:lanes` | 显示与 `origin/main` 比较后由差异触发的架构通道。 | | `pnpm check:changed` | 在选择执行方式前对变更通道进行分类。仅文档、无变更和小型元数据计划在依赖项已就绪时留在本地执行；具有类型检查/代码检查扇出、其他繁重通道或缺少本地依赖项的计划，会在 CI 外委派给 Crabbox/Testbox。不运行 Vitest；测试验证请使用 `pnpm test:changed` 或 `pnpm test `。 | ## 共享测试状态和进程辅助工具 - `src/test-utils/openclaw-test-state.ts`：当测试需要隔离的 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、配置固件、工作区、智能体目录或身份验证配置文件存储时，在 Vitest 中使用。 - `pnpm test:env-mutations:report`：以非阻塞方式报告直接修改 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、`OPENCLAW_WORKSPACE_DIR` 或相关环境变量键的测试/测试工具。使用它查找共享测试状态辅助工具的迁移候选项。 - `test/helpers/openclaw-test-instance.ts`：用于需要在一个位置统一处理运行中的 Gateway 网关、CLI 环境、日志捕获和清理的进程级端到端测试。 - 引用 `scripts/lib/docker-e2e-image.sh` 的 Docker/Bash 端到端测试通道可以将 `docker_e2e_test_state_shell_b64