在本地运行测试
常规本地顺序¶
pnpm test:changed用于变更范围的 Vitest 验证。pnpm test <path-or-filter>用于单个文件、目录或显式目标。- 仅在你有意需要完整本地 Vitest 套件时使用
pnpm test。
仓库包装器会将普通未过滤的 Gateway-server 运行模式选择和扩展的完整套件计划拆分为每个进程最多 50 个测试文件。这会在清单增长时限制非隔离模块图,同时不改变 worker 并发、堆限制或单个文件边界。原始 Vitest 和现有单次调用选择(例如显式目标、覆盖率、报告输出、bail 和 watch 模式)保留其现有行为。
扩展的完整套件运行会将基础设施和主机拥有的 SQLite 测试拆分为最多 64 个文件的批次。每个批次都在现有完整套件的 worker 预算内保留隔离的 fork worker。聚焦选择和 watch 模式保留其常规路由。
标记为 exclusive 的 Gateway 配置会在开始前排空其他测试计划,并在后续计划被接纳前完成。这适用于完整套件运行和显式 OPENCLAW_TEST_PROJECTS_PARALLEL 覆盖,也适用于自动精确目标调度。普通计划保留其配置的并行度。
创建真实托管 worktree 的测试必须满足容量和磁盘空间要求,包括为可执行 setup 脚本预留的额外空间。在整个运行期间保持该空间可用。
项目运行器会为单独的 --help 或 -h 请求打印包装器用法。复合请求(包括 --help --no-help)遵循原生 Vitest 选项语义。
现有的 UI 目录目标仍限定在该目录范围内,即使与显式 E2E 测试文件组合也是如此。测试保留其所属的 shared、isolated 或 browser 通道。需要整个通道覆盖的 UI 源文件/支持文件目标(例如共享样式或 setup 文件)仍会使用更宽泛的回退;如果你希望运行范围受限,请使用目录或显式测试文件。
当一次性路由运行仅针对显式测试文件路径时,每个选中的 Vitest 调用必须发现至少一个测试文件。排除所有选中文件会导致失败,即使该通道通常允许空运行。若要有意允许该结果,请使用 pnpm test <test-file-path> -- --passWithNoTests。使用 --passWithNoTests=false 显式要求非空发现。更宽泛的选择器和源派生选择保留其通道默认值。
通过 scripts/run-vitest.mjs 的显式 --config 运行保留其更严格的命名文件策略,并且不允许空的命名文件运行。插件 --allow-no-tests 和 --allow-empty-after-exclude 控制项保持不变。
Codex 和其他 linked/sparse worktree 可以运行本地测试和检查。工具要求已准备好的依赖项;它不会创建到主 checkout 的隐式链接。当另一个任务使用某个已借用的安装时,保持该现有借用安装不变。源安装的 pnpm:devPreinstall 检查会在正常依赖协调之前,拒绝 checkout 根模块目录及其 .pnpm 目录中的借用链接。它不会检查每个 workspace 包的依赖项或 lock 路径是否受到并发替换的影响;--ignore-scripts 会跳过它,并且替代的 pnpm 目录设置不会经过全面验证。当依赖项就绪后,使用上述常规命令。为避免 pnpm 的包管理器预检针对现有共享安装,请使用这些直接的 Node 运行器:
- 依赖项就绪时的有界聚焦验证:
node scripts/run-vitest.mjs <path-or-filter>。 - 变更的 typecheck/lint/guard 验证:
node scripts/check-changed.mjs。
新的源安装会从 pnpm store 克隆包文件,当文件系统无法克隆时回退为复制。因此,不同的 checkout 会保持独立的文件元数据:在其他位置安装依赖项不会通过共享硬链接更改活动编译器输入的修改历史。现有的硬链接安装不会被最新的 pnpm install 转换;对于隔离验证,请使用新的任务专属 checkout 和安装。不要在另一个任务使用某个安装时重新安装借用依赖项或替换该安装。
对于 Control UI 路由测试,运行 node scripts/run-tsgo-core-test-shards.mjs ui 以检查 fixture 类型;node scripts/run-tsgo.mjs -p tsconfig.ui.json 会检查生产 UI 代码并排除测试。针对 loader 所需的能力为路由 fixture 编写类型,而不是将部分 fixture 断言为完整的应用上下文。在生命周期测试中保留真实的选择能力,以便 agent 作用域变化和订阅清理遵循应用行为。
对于远程环境验证,直接调用 node scripts/crabbox-wrapper.mjs。在 linked worktree 中避免使用本地 pnpm crabbox:run,因为 pnpm 可能在远程包装器启动之前协调依赖项。
核心命令¶
在 Node 24.16+ 或 Node 26.1+ 上运行测试工具链,以匹配打包的运行时下限。较旧的 Node 绑定可能会在嵌入的 NUL 字符处截断 SQLite TEXT 值。
要在 Node 和 Bun 上比较相同的 Vitest 选择,请使用现有包装器:
OPENCLAW_VITEST_RUNTIME=node pnpm test <path-or-filter>
OPENCLAW_VITEST_RUNTIME=bun pnpm test <path-or-filter>
安装由 .github/actions/setup-test-bun/action.yml 固定的精确 Bun fork 构建,以获得可比较的结果。这会选择实际的 Vitest 进程和 worker,同时保留 Node 用于编排和编译器准备。源运行器 CLI fixture 也会在 Node 完成构建准备后使用所选运行时。这不会使用 Bun 的原生测试运行器。仅 bun run 不会为测试选择 Bun。Node 仍是本地默认。
对于 CI Control UI 比较,先在 Node 上运行完整选择,然后在 Bun 上运行:
OPENCLAW_NODE_TEST_CONFIGS_JSON='["ui/vitest.config.ts"]' \
OPENCLAW_NODE_TEST_VITEST_ARGS_JSON='["--maxWorkers", "3"]' \
OPENCLAW_CI_TEST_RUNTIME_POLICY=dual \
node --import tsx scripts/ci-run-node-test-shard.mts
Both passes include the retention assertions, which use runtime-neutral garbage
collection and WeakRef checks. Run the complete UI selection only on Bun with
OPENCLAW_VITEST_RUNTIME=bun.
测试进程及其 CLI 夹具保持启用 Sparkplug 基线编译,但同步运行它。这避免了 Node 24 关闭死锁:后台编译器等待主线程垃圾回收,而 process.exit 会等待该编译器完成。共享的 Node 参数策略拥有此仅限测试的缓解措施;生产 CLI 退出行为、断言和截止时间保持不变。
脚本可擦除性门控使用 Node 的仅剥离解析器,即使包检查在 Bun 下运行时也是如此。它会选择一个已安装的 Node 运行时,并跳过 Bun 的 node 垫片。需要 node:module.registerHooks 或 stripTypeScriptTypes 的维护者工具测试也会为其工具子进程显式选择 Node。使用来自 test/helpers/node-toolchain.ts 的 requireNodeTool("node") 和 stripNodeTypeScriptTypes,它们共享该 Node 选择所有者,同时让 Vitest worker 保持在所选测试运行时上。
隔离的原生 worker 和子进程夹具使用来自 test/helpers/native-module-mock.ts 的 mockNativeModuleExports,以便在任一运行时上受控地导出模块。这些 mock 会一直存在到该子进程退出。在注册替换之前捕获原始直通函数,因为 Bun 会更新现有模块命名空间绑定。
测试工具链固定稳定的 Vitest 5.0.1,包括其浏览器和覆盖率包。对有序套件使用 describe(name, { concurrent: false }, callback)。等待异步断言,将 vi.mock/vi.hoisted 保留在模块作用域,并在测试内部执行你断言其 mock 调用的操作。OpenClaw 设置 clearMocks: false,因此 setup 和 beforeAll 调用会被保留。根据需要显式清除或重置每个断言拥有的 mock 操作。跨套件名称模式使用 suite > test;原生 JSON 保留其以空格连接的 fullName,因此证据读取器匹配 ancestorTitles 加上 title。
文件系统转换缓存使用 test.fsModuleCache 和 test.fsModuleCachePath;现有的 OPENCLAW_VITEST_FS_MODULE_CACHE 和 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH 控制项保留其所有权和禁用行为。缓存键插件使用 defineCacheKeyGenerator。jsdom 通道通过 deps.optimizer.client 一起优化 Lit 及其导出的子路径。CodeMirror 和 Lezer 保留在 Vite 的模块图中,以便编辑器类和解析器属性保留单一依赖身份。当配置了 NODE_COMPILE_CACHE 时,测试启动器会为 Vitest 及其 worker 保留它。Vitest 为 V8 和自定义覆盖率提供程序在 worker 及其子进程中禁用字节码缓存;显式 NODE_DISABLE_COMPILE_CACHE=1 仍会禁用整个调用的缓存。内联项目在 Vitest 5 中继承根配置,包括拼接的 setup 和 include 数组。四个 UI E2E 资源项目声明 extends: false,因为每个项目都提供其完整清单和 setup。
维护的 JavaScript 工具包装器和根包命令通过 scripts/tsx.mjs 加载 TypeScript,使用 tsx 的 ESM 入口。这保留了已编译 ESM 插件及其仅导入依赖的原生加载,包括通过 require() 加载时。源 TypeScript 导入和 tsconfig 路径别名仍然可用。
这些启动器保留 tsx 的进程内转换缓存和 Node 的模块缓存。它们在加载器启动前跳过 tsx 的共享磁盘缓存,子工具继承该策略。此缓存策略不会清理现有临时目录、Node 或 Vitest 缓存,或其他全局缓存。独立的 pnpm ui:build 以原生方式启动,并直接使用 Node 运行其构建后验证器。这些验证器不会加载 tsx,也不要求在调用 shell 中设置 TSX_DISABLE_CACHE。在这些启动器之外的原始外部 tsx 和 node --import tsx 调用保持不变。
Node Vitest worker 也会每个 worker 预加载一次 scripts/tsx.mjs。Vitest 仍然拥有测试模块 mock,而原生插件 SDK 导入使用 Node 的源模块图,带有 TypeScript 语法和 .js 到 .ts 的解析。Bun 使用其原生 TypeScript 加载器。这使源宿主测试不依赖 Jiti 来评估宿主 SDK 的另一份副本。
在 macOS 和 Linux 上由调度器拥有的项目运行会在独占槽位内复用文件系统转换,包括混合配置的串行运行。每个 Vitest 配置保留独立目录。槽位通过预检、重试以及已验证的子进程/组完成保持拥有;不确定的清理会使其退役。没有调度器分配的相同配置串行运行、显式隔离缓存路径、watch 运行以及 Windows 保留其现有缓存所有权。并发调用仍需要独立的缓存根。
Control UI 构建会报告大小预算,但不强制执行它们。构建后运行 pnpm ui:check-performance 以强制执行绝对预算,或运行 pnpm ui:check-performance:base <base-commit-sha> 以使用相同工具链构建并比较两个修订版本。参见 Control UI 大小预算。
源测试与子进程构建¶
通过 pnpm test 或 scripts/run-vitest.mjs 的非 watch 运行会让 Vitest 测试和运行时父进程保持 TypeScript。导入已声明的子进程入口点会将固定的测试入口集及其工作区依赖编译到 .artifacts/vitest-workers/ 下的一个全新调用目录中。
已声明的应用程序入口作为普通 Node JavaScript 运行,不使用 TypeScript 加载器:SQLite 只读快照、数据库验证、Tailscale 路由所有权、服务中继、其 POSIX 和 Windows 锚点、内存插件的 KNN 子进程、会话转录归档和对账 worker,以及受管理的 GitHub 凭据解析。同一生成过程还会一起编译 fake-backend TUI 夹具的四个运行时根:真实 TUI、嵌入式回复生产者、回复元数据读取器和出站规范化器。共享块保留其模块和 WeakMap 身份。准备好的 TUI 夹具被编译为 .mjs,并作为 JavaScript 运行,不使用 TypeScript 加载器。直接源夹具保持为 .mts:Node 使用 --import tsx 启动它们,而 Bun 原生处理其语法。会话身份 PTY 测试会加载真实提供商策略,因此其运行时前置条件会在 Vitest worker 启动前准备已构建的宿主 SDK。现有包构建入口路径和 Vitest 源父进程保持不变。CLI fork 恢复回归测试还会一起编译真实 CLI 入口及其并发 rebind 的会话访问器和绑定辅助函数。两个进程使用相同的运行时图,同时保留持久写入竞争和进程退出断言。禁用捆绑插件的 Doctor 进程输出测试会在每次测试运行中复用一个惰性创建的包夹具内的该已编译 CLI,使真实 UI 检查保持在夹具拥有的资产上,并使每个场景的状态相互隔离。独立运行和 watch 运行在同一夹具内使用实时源。
广播输出覆盖会一起准备其消息辅助模块和退出终结器, 保留命令替换,并在测试夹具清理前等待其进程树结束。
隔离的 Doctor 配置脚本也共享已准备的 config-flow、health-writer 和 install-index 模块。每个用例仍启动一个具有独立状态的全新进程;独立运行和 watch 运行解析原始 TypeScript 入口点。
model-catalog、Codex catalog-page 和 session model-context 工作线程也使用该已编译产物代。 model-catalog 工作线程仍属于其已准备的模型编译产物代;上下文读取 保留其串行工作线程池。插件 source/built 选择仍独立于 工作线程编译。 其他工作线程入口和任意 source CLI 测试夹具仍位于 该声明集合之外。
agent 数据库模块身份测试共享已编译的 host 和 SQLite SDK 入口,同时强制对 SDK 进行单独的插件转换。其独立运行和 watch 运行保留来自当前源代码的一次性构建,因为该回归测试 专门检查打包后的模块图。两种模式使用相同的断言和 子进程截止时间。
session-title 和 child-link 保留测试在同一编译产物代中声明其 title-reader、 session-utils 和 listing 根。每个全新的 堆测量子进程运行其 JavaScript,而不会将执行 截止时间消耗在 TypeScript 导入上。
Automatic-triage 进程测试夹具共享该编译产物代,用于准入、故障处理、执行、进程身份和重生检查。编译在就绪截止时间开始之前完成,因此子进程加载已准备的 JavaScript。分离的辅助进程使用与已安装包相同的密封租约运行时。
已知的核心 database-worker 消费者在测试进程启动前准备该调用的已编译产物代, 包括当某个用例动态导入其工作线程声明时。选择使用现有的 database-worker 清单,并遵循 CLI 过滤器、排除项和包含文件。其他测试在项目和 分片之间保留惰性准备。配置导入、列表测试、watch 运行、自定义选择 以及不导入这些声明的小型测试不会立即编译工作线程。 导入声明的分片通过其现有 Node IPC 通道请求外部运行器的单一构建;立即消费者复用已完成的编译产物代。 静态导入在模块收集期间获取它,早于测试夹具钩子和就绪 截止时间。每个需要声明的有限调用 都会承担该固定入口集合的成本;准备耗时与子进程执行分开报告。运行器启动一个短生命周期的原生 Node 或 Bun 编译器子进程,并在向借用者返回已验证的清单之前等待其结束。编译器模块图位于该子进程中,而不是长生命周期的运行器 或 Vitest 工作线程。任何分片都不能选择不同的构建图或采用另一个调用的输出。外部 运行器保留该编译产物代,直到子进程关闭和进程组清理 完成,然后在报告成功前验证它。验证使用有界异步 I/O 读取每个已记录的 输入和输出,使运行器在大型关闭扫描期间保持响应。调用所有者在回复前验证每个借用者的准备, 并在所有借用者关闭后再次验证;Vitest 不会在每个分片内部或其并发池关闭期间重复 这些扫描。独立 Vitest 运行和 watch 运行保留源代码执行:编译、验证和产物 删除需要仓库运行器的所有权。 所有者丢失或构建失败会使运行失败。 处置会取消待处理的编译并等待其结束、等待每个借用者以及未完成的 准备请求,然后异步删除目录。信号处理器 在删除过程中保持激活,即使大型编译产物代需要较长时间删除。 借用者完成不会等待编译,因此子进程提前退出可能到达该取消路径。不确定的编译器或借用者等待会保留该 编译产物代并使运行失败。异常终止也可能留下未使用的 目录;后续运行永远不会采用它。
每次准备都编译当前源代码;checkout dist/ 既不是输入
也不是回退。构建错误、缺失产物以及对已记录构建
输入的更改会使运行失败。编译在原生子进程测试夹具
施加资源限制之前包含它们。第三方依赖保持外部,始终打包的
OpenClaw 包除外。fs-safe 保持外部,以便其原生加载器
从 fs-safe 自身的依赖范围解析可选平台包,包括
嵌套的 pnpm 安装。已编译的工作线程使用同一已安装包;它们不
复制原生二进制文件。原生模式在 macOS、Linux 和 Windows 上默认为 auto。
无覆盖 Root 移动需要原生支持;Windows 安全凭据读取
需要匹配的辅助程序,用于描述符绑定的 ACL 检查。显式
off/auto/require 设置和编程配置保留其
优先级。密封的可移植工作线程包仅使用受保护的 JavaScript,并
显式禁用原生加载。
watch 模式有意保留现有的实时源代码路径,包括用于 Node 子进程的 tsx 和用于 Bun 的原生 TypeScript 处理。它不创建已准备的编译产物代,因此新的子进程启动 读取当前源代码,而不是复用已编译快照。现有 Vitest watch 依赖跟踪仍决定测试何时重新运行。
测试包装器运行以简短的 [test] passed|failed|skipped ... in ... 摘要结束;Vitest 自身的耗时行仍作为每个分片的详细信息。
失败的调用在子进程、清理和报告发布稳定后,以一行 [test] FAILED (exit N) 结束。直接 run-vitest.mts 调用
改用 [vitest]。嵌套运行器保留其诊断信息和退出状态;
顶层 CLI 拥有最终失败行。成功运行不输出失败
尾注。
| 命令 | 它的作用 |
| 命令 | 作用 |
|---|---|
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
pnpm test |
显式文件/目录目标会路由到作用域化的 Vitest 泳道。未指定目标的运行是全量套件验证:固定分片组会展开为叶子配置以进行本地并行执行,并在开始前打印预期的分片扇出。扩展组始终展开为按扩展的分片配置,而不是一个巨大的根项目进程。 |
pnpm test:changed |
低成本的智能变更测试运行:来自直接测试编辑、同级 *.test.ts 文件、显式源映射以及本地导入图的精确目标。除非映射到精确测试,否则跳过广泛/配置/包变更。 |
OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed |
显式广泛变更测试运行;当测试框架/配置/包编辑应回退到 Vitest 更广泛的变更测试行为时使用。 |
pnpm test:force |
释放已配置的 OpenClaw 网关端口(默认 18789),然后使用隔离的网关端口运行完整套件,使服务器测试不会与正在运行的实例冲突。 |
pnpm test:coverage |
为默认单元测试泳道(vitest.unit.config.ts)输出信息性的 V8 覆盖率报告;不强制任何覆盖率阈值。 |
pnpm test:coverage:changed |
仅针对自 origin/main 以来变更的文件生成单元测试覆盖率。 |
pnpm changed:lanes |
显示相对于 origin/main 的差异所触发的架构泳道。 |
pnpm check:changed |
运行本地变更格式化/类型检查/lint/guard 计划,包括针对所选路径的定向 Vitest owner 测试。使用 pnpm test:changed 或 pnpm test <target> 获取与所触及契约匹配的额外测试验证。 |
pnpm check:changed 还会在变更影响网关事件目录或常量、被扫描的移动端源、覆盖率声明,或该守卫、其执行辅助函数及其路由时,运行移动端协议事件覆盖率守卫。所有泳道检查也都包含它。每个网关事件都必须具有一个处理器,或者对每个移动客户端具有一个明确批准的非消费声明。若只想运行此守卫,请使用 pnpm check:protocol-coverage。
对于原生应用变更,pnpm check:changed 使用平台范围来选择 lint:Android 选择 pnpm android:lint(Gradle ktlint 检查),而 Apple 应用变更保留 Swift lint。仅 Android 的变更不会选择 Swift lint 或其缺少工具提示。Android 框架/资源 lint 和运行时测试仍是独立检查;Kotlin lint 不会替代它们。
执行 GNU stat 和 readlink 的远程文件系统 fixture 仅在 Linux 上本地运行。共享的前导 @ 文件工具场景也在每个平台上针对可移植的仅远程桥接运行。原生 Python 辅助函数覆盖率仍保持独立,包括 macOS;这些 fixture 门控不会限制 SSH 后端的 Gateway 主机。
发现真实捆绑 provider 运行时的测试会在 scripts/lib/vitest-build-prerequisites.mts 中声明该前置条件,包括 Telegram 贴纸模型选择。本地运行器和 CI 会在接纳 worker 之前准备这些产物。
本地 PR 门禁¶
对于本地 PR 落地/门禁检查,请运行:
pnpm check:changedpnpm checkpnpm check:test-typespnpm buildpnpm testpnpm check:docs
pnpm check --base <ref> 将行上限、max-lines 抑制以及断言安全棘轮固定到 HEAD 与该 ref 的合并基。原生 PR 门禁会传递其候选者基于捕获的 main 快照的 fork,因此继承的 main 变更即使共享的 origin/main ref 已过期,也会保留其允许值。其他检查阶段仍会正常运行。
如果 pnpm test 在负载较高的主机上出现偶发失败,请先重跑一次,再将其视为回归问题,然后用 pnpm test <path/to/test> 单独隔离。对于内存受限的主机:
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm testOPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw