跳转至

测试运行器内部

共享测试状态与进程辅助工具

TypeScript 工具链使用原生 typescript 包。pnpm tsgo 通道直接解析其可执行文件;语法和语义工具使用其不稳定 API,并具有显式的进程生命周期。包根目录导出版本元数据,而 AST、文件系统和编译器 API 位于 typescript/unstable/* 下。打包的声明构建使用相同的原生编译器进行语义检查,并在打包前验证其完整的源代码和包清单收据。tsdown 包装器默认声明构建一次一个配置,在现有 Node 堆预算之外限制原生编译器进程。仅运行时的构建保持其并行性,显式的 --concurrency 值保留 tsdown 自身的行为。Code Mode 直接执行 JavaScript,不使用此编译器;其 TypeScript 风格的工具声明是面向模型的文档。

build-all、独立的 tsdown 构建、tsgo、SDK 声明准备、包边界检查以及相关 lint 使用 .artifacts/dist-artifacts.lock 处的 checkout 本地所有权。所有权涵盖清理、生成、缓存恢复以及消耗这些输出的检查;独立的 checkout 保持独立。竞争的命令会打印等待消息,并在没有获取期限的情况下等待活跃的所有者。编译器和构建执行超时保持不变。独立的 tsgo 运行会串行化,包括仅源代码检查;核心测试分片运行器在一个所有者内保留其显式并发。在这些命令运行时,不要手动删除 dist。所有者或嵌套包装器的突然退出,或未经验证的子进程清理,会保留锁。缺少或无法验证的所有者 PID,或记录的子进程清理失败,会立即导致获取失败,且不回收任何内容。PID 死亡并不能证明分离的后代进程已停止。在手动删除废弃的锁目录之前,请检查其 owner.json,并验证所有关联的构建、编译器和 lint 进程(包括分离的后代进程)都已停止;然后重试该命令。

消耗运行时的测试通过显式构建所有者准备 checkout 工件,而不是通过使用 --version 启动 CLI。准备过程复用源代码运行器的新鲜度检查和 checkout 工件所有权,不涉及更新器服务或数据库维护托管。当前工件不需要可写的 checkout 或服务检查。build-all 在现有印记中对生产输入进行指纹识别。测试准备可以在源代码刷新或仅测试修正后复用一致的运行时,包括新的私有传输提交。普通 CLI 和不可变部署的 HEAD 检查保持严格;UI E2E 准备也保留其当前 HEAD 检查。变更的生产输入、构建配置、依赖项、编译器身份或必需的缺失输出仍需要准备。跳过静态资产的部分后置构建无法满足需要这些资产的读取者。E2E 检查前的完整构建应使用 OPENCLAW_BUILD_PRIVATE_QA=1 pnpm build;将该标志限定在构建命令范围内,以便其工件满足最严格的测试前提条件。

在写入之前,自动准备需要经过验证的工件分离或观察到的离线托管 Gateway。在 Linux 上,它使用现有的原生管理器绑定读取已加载的命令位置,而不读取服务环境文件。原生 GetUnit 的 not-loaded 结果确定没有已加载的运行时,而不是缺少其保存的定义。未加载的已保存单元不会使原本可写的源代码 checkout 变为不可变;这是准入时检查,而非服务启动排除或沙箱。物理共享的 dist 路径、不可读的工件路径、不完整的发现以及未知的服务状态绝不会授予重建权限。不可变部署和已知的活动重叠仍然被拒绝。对于普通的独立工作树,不需要新的 CLI 标志或配置;当无法建立原生隔离时,请使用现有的隔离运行器。此检查不是沙箱。显式的 pnpm build、自动源代码 CLI 重建以及实际更新发布保留其现有的准入策略。

Lint 在子进程汇合和工件所有权确定后,在 stderr 上报告其最终失败,包括在清理不确定时保留所有权的情况。独立的 Oxlint 及其分片 CLI 以 [oxlint] FAILED (exit N) 结束;pnpm lint 拥有整个流水线,并以一个 [lint] FAILED (exit N) 结束。分片进度区分 passed 和 failed (exit N),stdout 仍可用于机器可读的工具输出。成功的运行没有失败尾部信息。子进程执行期间转发的信号和分片超时会导致命令失败;整个主机丢失或报告进程的 SIGKILL 可能会阻止最终行的输出。

本地插件 lint 使用 packages/plugin-sdk/dist 中的原生 SDK 声明。专用的包边界编译器还使用 .artifacts/extension-package-boundary/plugins 中的七个插件 API 树。每个声明和编译所有者验证其使用的源代码内容、继承的配置、选定的编译器以及完整的输出清单。无关的现有源代码或测试编辑保留缓存命中。解析拓扑变更会保守地使缓存失效,包括声明根之外的新模块候选。过时的声明在其私有输入收据被清除后获得完整的原生 emit;成功发出的清单随后驱动过时声明的修剪。缺失或被篡改的输出会使所有者失效。内容记录位于 .artifacts/extension-package-boundary 下,在打包构建清理之外。私有 .inputs.json 收据包含规范化的 checkout 相对源代码和清单路径,而不是原生 .tsbuildinfo 状态。预热运行验证记录,而不 emit 声明。

打包的声明构建和包边界记录仅接受 checkout 拥有的输入真实路径,包括编译器库、继承的配置、依赖链接和包清单。这些路径共享 compileNativeProject,它使用固定的原生编译器的异步 API 进行检查和内存中声明 emit。其文件系统回调使 checkout 之外的候选在原生解析读取它们之前表现为缺失。源代码和包清单读取被直接捕获;准入不依赖于对解析跟踪记录的解析。编译器版本固定在 package.json 中,因为此 API 不稳定。配置和请求的语义检查在 emit 之前运行。声明错误来自内存中的 emit 结果,避免仅为诊断而进行单独的声明转换。任何错误都会阻止工件发布。

嵌套的物理工作树受支持,它们可以拥有自己的 pnpm install --frozen-lockfile,即使祖先目录包含 node_modules 也是如此。祖先依赖无法满足缺失的本地输入,也无法改变已生成的声明。当本地 pnpm 链接的目标保持在检出目录内时,这些链接仍受支持。解析到检出目录之外的本地链接仍会以 Declaration input escapes checkout 失败,不会发布成功记录,也不会清理过时的声明。外部候选对象即使是指回检出目录的符号链接,也仍然不可访问。热记录使用相同的输入检查。不要过滤编译器收据,也不要移植声明来绕过这些检查。

已声明的检出联接点和平台路径别名映射到相同的原生根目录,用于验证和实际快照读取。本地声明准备还会将编译器的 PWD 与其工作目录对齐,从而使 shell 别名不会改变生成的清单路径。从子目录发起的调用仍以包含该子目录的检出目录作为所有权边界。其他 pnpm tsgo 通道继续使用原生 CLI;其包装器不会创建或复用共享的外部安装。

打包的 SDK 声明属于一个暂存所有者,由 full、package 和 ciArtifacts 构建共享。在未命中时,它会序列化两个规范的 tsdown SDK 组,并缓存其完整的暂存生成结果。每次成功的编译都会通过私有暂存收据提供其源代码和包清单成员资格;收据缺失或编译期间输入发生变化都会阻止发布。共享输入快照策略会验证已消费的字节、继承的配置、生成器和清单输入以及解析拓扑,命中时不会启动编译器。缓存命中会还原到全新的暂存区,并在发布前通过相同的入口和相对声明闭包检查。

所有 tsdown 声明构建(八个 SDK/统一组、工作区包和 AI 包)都使用与本地声明准备和包边界检查相同的受限编译器。成功的构建需要检出目录所有的编译器库和声明依赖;不支持共享的外部安装。编译器收据保留完整的源代码和包清单成员资格,包括 JSON 输入。默认类型根保持在检出目录内,显式类型根必须是本地的,有效的根 package.json 限定了源包作用域查找的范围。

共享快照策略仍会验证已消费的字节和解析拓扑。编译期间的源代码和命名空间变化会阻止其被接受。新的本地模块候选会使缓存记录失效,祖先安装的出现和移除也同样如此。外部检查始终看到缺失的文件,因此之后对祖先包内容的更改无法进入编译器的文件系统视图。在成功的编译器成员资格中,每个已生成的声明都必须有一个源映射所有者。打包器会在其原始源路径下消费这些声明;私有编译器阶段仅在其子进程完成后才被移除。编译器配置、原生可执行文件和 API 文件、输入字节以及解析拓扑都会参与缓存失效。运行时模块解析保持不变。

本地准备永远不会覆盖打包的声明,也不会写入工作区转发桥。

插件 SDK 声明准备和 scripts/run-tsgo.mjs 要求子进程完成后才能报告成功。在 POSIX 上,两者都会验证其自身管理的进程组:残留子进程会被终止,命令会失败,而不是允许产物标记或下游检查继续执行。POSIX 进程组无法检测故意离开该组的后代进程。

在 Windows 上,受管命令和 Gateway 测试实例使用保留的内核 Job。仅当请求 Windows 命令时才会加载平台代码;规划器导入保持独立于已安装的应用程序包。加载在生成之前完成,因此监听器注册与子进程创建保持同步。工具使用 Node 内建模块解析其 worker URL,并复用核心中的原生 Job 绑定。启动器在启动命令之前加入该 Job。清理过程会等待 Job 为空、领导者退出和输出关闭;仅领导者退出永远不能证明后代进程已完成。终止失败时,会报告观察到的存活 PID,并在 Job 仍未完成期间保留资源声明。正常的领导者退出也会终止剩余的 Job 成员。收尾会在关闭 Job 句柄之前记录其结果,包括失败时也是如此;仅关闭句柄并不能验证终止或释放资源声明。具有自身 IPC 通道的现有调用者保持直接启动契约;在不拥有 Job 的情况下,即使领导者及其管道已关闭,失败的 taskkill 仍保持不确定状态。

run-vitest(包括项目分片)、插件批次、test-live(包括实时分片)、run-vitest-profile 和 TUI PTY 监视器通过 TMPDIR、TMP 和 TEMP 为每次 Vitest 调用提供专属的临时命名空间。在 Vitest 启动之前,隔离调用还会在该命名空间内获得原生 HOME 和 USERPROFILE。这样可以保护工作线程、命名内建导入以及导入时捕获所使用的主目录回退;仅更改工作线程的 JavaScript process.env 不会改变原生线程的主目录查找。每个工作线程和每个测试的夹具主目录保持分离。已安装的 Corepack 和 Playwright 浏览器缓存保留其调用者选择的位置。

Gateway 端口声明保留在公共临时目录中,该目录位于所有封闭的 Vitest 命名空间之外,并通过其显式的资源所有者找到。因此,当一个夹具将其保留的套接字交给子进程时,并行调用共享端口所有权;删除一个调用的文件不会删除另一个夹具的端口声明。

在共享池端口上绑定 Gateway(进程内或已生成)的夹具,从选定之时起持有该端口的声明,直到 Gateway 关闭。Gateway 在启动时会重试繁忙端口,因此未声明端口的夹具可以在另一个夹具的交接期间占用其端口。getDeterministicFreePortBlock 是一种检查,而不是租约;进程内 Gateway E2E 夹具会结合 startClaimedGateway 使用 acquireGatewayE2ePortBlock。

Live-aware setup still loads the original profile and stages live state when requested. A bounded invocation artifact carries the original home to that setup; it does not grant live access, and hermetic setup never consults it. Known hermetic selections ignore ambient live and real-home flags. Known wholly live-aware selections retain explicit OPENCLAW_LIVE_USE_REAL_HOME behavior. An explicitly real-home live invocation is refused before config loading if its selection mixes home policies or cannot be classified, including custom configs and ambiguous project selectors. Run hermetic tests without LIVE, OPENCLAW_LIVE_TEST, OPENCLAW_LIVE_GATEWAY, and OPENCLAW_LIVE_USE_REAL_HOME using node scripts/run-vitest.mjs <test-path>, then run the intended live selection separately using node scripts/test-live.mts -- <live-test-path>. The launcher does not split runs or change watch, filter, or report semantics.

实时感知设置仍会加载原始 profile,并在请求时暂存实时状态。有界调用工件会将原始 home 带到该设置;它不授予实时访问,隔离设置也从不查询它。已知隔离选择会忽略环境中的 live 和 real-home 标志。已知完全实时感知的选择保留显式 OPENCLAW_LIVE_USE_REAL_HOME 行为。如果显式 real-home 实时调用的选择混合了 home 策略或无法分类,包括自定义配置和模糊的项目选择器,则会在加载配置前被拒绝。在不带 LIVE、OPENCLAW_LIVE_TEST、OPENCLAW_LIVE_GATEWAY 和 OPENCLAW_LIVE_USE_REAL_HOME 的情况下,使用 node scripts/run-vitest.mjs <test-path> 运行隔离测试,然后使用 node scripts/test-live.mts -- <live-test-path> 单独运行预期的实时选择。启动器不会拆分运行,也不会改变监视、过滤或报告语义。

该命名空间包含隔离的 home、它们的 JIT 缓存、SDK/共享 home 分配根以及回退 SQLite 状态;其生命周期覆盖共享 worker 文件和模块重置。在 POSIX 分离启动中,父进程仅在子进程组停止、输出管道关闭,并且嵌套资源所有者释放其待处理声明后,才移除该命名空间;这包括通过和失败的运行、子进程崩溃、捕获的 SIGINT/SIGTERM 信号,以及在受支持情况下的看门狗终止。命名空间之外的显式状态、profile 输出和镜像工件保持不变。失败或未经确认的组加入,或未解决的嵌套声明会保留命名空间,并报告确切路径以便手动恢复。嵌套命名空间、fixture 生命周期和受管命令在允许工作之前注册临时文件系统所有权。释放需要明确的完成证据;捕获的清理失败、模块重置、worker 退出或中间 runner 崩溃都不能释放待处理声明或其祖先。受管命令保持其现有的输出排空契约;Windows Job 命令还会加入内核 Job 完成。失败的终结处理从不释放所有权。在手动删除报告的确切目录之前,停止所有剩余写入者。Windows 和非分离启动会分配相同的隔离原生 home,但由于无法验证后代完成,会在子进程退出和管道关闭后保留其命名空间及外层声明,并附带诊断信息。原始外部调用不会获得此边界。强制父进程或监督进程死亡(例如 SIGKILL)可能阻止清理;有意逃离受管组的未注册后代仍在此契约之外。包装器不会清扫旧目录,也不会根据名称、年龄或 PID 推断所有权。CI 分片 runner 还会在每个被允许的组加入后移除其默认 include-file 和 transform-cache 临时目录。调用方提供的临时目录和持久缓存根仍归调用方所有。未经确认的后代完成会保留分片临时目录,并报告其确切路径。这是 home 隔离,而不是文件系统沙箱:显式绝对路径、os.userInfo() 账户查找、home 变量被剥离或替换的子进程,以及有意使用 real-home 的实时执行均不在其保护范围内。

Codex app-server fixture 在测试用例之间等待 agent 和共享状态 SQLite 排空。它们的文件拆除会排空共享磁盘预算扫描 worker,在文件期间保留重用,并在隔离 fork 关闭前释放它。

  • src/test-utils/openclaw-test-state.ts:当测试需要隔离的 HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、配置 fixture、工作区、agent 目录或 auth-profile 存储时,在 Vitest 中使用它。
  • pnpm test:env-mutations:report:对直接修改 HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、OPENCLAW_WORKSPACE_DIR 或相关 env 键的测试/测试框架的非阻塞报告。使用它来查找共享测试状态辅助函数的迁移候选项。
  • test/helpers/openclaw-test-instance.ts:需要在一个地方运行 Gateway、CLI 环境、日志捕获和清理的进程级 E2E 测试。
  • 加载 scripts/lib/docker-e2e-image.sh 的 Docker/Bash E2E 通道可以将 docker_e2e_test_state_shell_b64 <label> <scenario> 传入容器,并使用 scripts/lib/openclaw-e2e-instance.sh 解码它;多 home 脚本可以传递 docker_e2e_test_state_function_b64,并在每个流程中调用 openclaw_test_state_create <label> <scenario>。node --import tsx scripts/lib/openclaw-test-state.mts -- create --label <name> --scenario <name> --env-file <path> --json 会写入一个可 source 的主机 env 文件(create 前的 -- 可防止较新的 Node 运行时将 --env-file 视为 Node 标志)。启动 Gateway 的通道可以加载 scripts/lib/openclaw-e2e-instance.sh,用于入口点解析、模拟 OpenAI 启动、前台/后台启动、就绪检查、状态 env 导出、日志转储和进程清理。

createOpenClawTestState 选择并拥有临时路径和进程环境选择器。它不是文件系统沙箱,也不会阻止外部生产者。等待其异步 restoreEnv();在恢复选择器或删除状态之前,停止并等待所需生产者结束。状态选择泄漏的运行时复现需要强制的存储隔离,例如无法访问操作员存储的 VM 或容器,而不仅仅是临时 HOME 或状态目录覆盖。

公共测试诊断

共享 Vitest reporter 工厂在将断言消息、diff、期望/接收值、堆栈、源代码摘录和注释转发到所选 reporter 之前,会脱敏凭证形状的字段。键保持可见,值变为 <redacted len=N>。这也适用于显式 --reporter 选择、UI/浏览器配置以及 JSON/JUnit 报告。托管日志是公开的,runner 签发的令牌可能未注册用于 GitHub 掩码。

未加引号的环境记录每行使用一个赋值:右侧的空格和标点属于该值。被 Node 检查器拆分为带引号片段的字符串会作为一个值脱敏。

脱敏是无条件的,影响诊断输出,而不影响断言行为。 测试控制台捕获不在此边界内;测试仍必须避免直接记录凭据。

已配置的扩展 fork 项目使用围绕 Vitest 原生 fork 传输的 openclaw-forks 诊断适配器。如果现有停止截止时间失败,而子进程仍然存活,适配器最多再花费两秒收集 Node 报告,然后进行原生终止和管道清理。超时仍然算作测试失败。报告区分缺少停止确认与确认后的停滞,并包含原生堆栈、libuv 句柄和工作线程报告。环境变量、命令参数和套接字端点会被省略。被阻塞的事件循环可能阻止信号报告;该情况会明确报告未捕获到完整报告。

成功关闭保持静默。显式 --pool=forks 会选择 Vitest 内置池并绕过此适配器。

跨原生进程的 JSON 报告

对于多项目或分块运行,请显式请求带输出文件的原生 JSON,例如:

pnpm test test/vitest/vitest.unit-fast-isolated.config.ts test/vitest/vitest.agents-embedded-agent.config.ts --reporter=verbose --reporter=json --outputFile=.artifacts/test-results.json

项目运行器和插件批处理运行器为每次尝试提供独立的原生 JSON 和 blob 文件,然后从 Vitest 的原生报告合并中发布所请求的 JSON。它们会打印一个伴随的 <output>.reports-<unique> 目录。请保留该目录:它包含原始报告、启用覆盖率时的每次尝试覆盖率文件,以及一个 index.json,其中包含子进程退出码、信号、超时和未启动的工作。每次调用只运行一次。无输出超时会使命令失败,并使报告集不完整;它永远不会启动替代尝试。Blob 报告是精确版本工件。在合并由其他版本生成的工件之前,请使用当前 Vitest 版本重新运行子报告。

聚合结果保留已接受的用例清单,但并非原始结果的无损替代。原生合并不会恢复快照摘要或 JSON coverageMap,并且其 startTime 是合并时间。通过的快照测试仍然成功。请阅读原生原始文件以获取这些细节,并阅读索引以获取进程结果:JSON success 不会编码所有包装器失败或未处理错误失败。独立的内置覆盖率报告仍按尝试保留在伴随目录中。自定义覆盖率提供程序/报告器以及覆盖率报告器元组选项需要具有唯一目标位置的单独调用。

完整的失败测试聚合结果会随失败的命令退出而保留。缺失或无效的证据、取消、未启动的必需工作或发布失败不会发布完整聚合结果;现有输出文件不是新运行的证明。诊断会打印保留的报告集位置。报告集不会被自动清理。

重叠的选择可能共享原生任务 ID,因此合并它们可能会替换独立的失败细节,即使用例数量匹配。此类报告集会保留其原始文件并导致发布失败。每个配置只选择一次,或分别运行重叠的选择并使用不同的输出文件。

此所有权适用于带有命名、基于文件的 Node 项目和原生控制台报告器的显式 CLI JSON 文件请求。标量 --outputFile 和 --outputFile.json 均可用。配置拥有的报告器选项、其他文件格式、自定义报告器以及内联/浏览器项目组合需要具有唯一输出目标的单独原生调用。不要假设这些输出已被聚合。单进程和仅控制台运行保持其现有原生行为。原生帮助和其他非测试控制保留在子 CLI 中,并且不会分配报告集。run --version 仍然会运行测试,正如原生 Vitest 中一样。仅配置的报告器不会被拦截:多个子进程仍可能覆盖同一配置文件。请分别运行这些配置并使用不同的路径;仅添加 --reporter=json 不会覆盖报告器元组自身的 outputFile。

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