跳转至

控制 UI、TUI 和 E2E 泳道

控制 UI、TUI 和扩展泳道

  • 浏览器 MCP 契约: pnpm test:e2e:browser-mcp 会安装固定版本的 Playwright Chromium,并通过 stdio 针对一次性浏览器配置文件启动已配置的 Chrome DevTools MCP 服务器。它覆盖原生操作、跨条件等待的 refs、frame 标签、导航策略检查,以及在 npm/pnpm 打包和离线 npm 安装过程中保留已修补的依赖。按路径过滤的 Browser MCP contract 工作流会在 MCP 实现和依赖变更时运行此命令。其 contract-bun 作业会在固定版本的 Bun fork(OPENCLAW_VITEST_RUNTIME=bun)上运行 Chromium 契约文件,这是 macOS 和 Linux 桌面应用唯一的运行时。要验证候选服务器构建,请将 OPENCLAW_BROWSER_MCP_TEST_COMMAND 设置为其可执行启动器。启动器必须转发其参数,并为坐标操作启用 --experimentalVision;OpenClaw 会提供端点和结构化内容标志。请使用该证明记录服务器来源/版本。这些测试不会附加到用户的 Chrome,也不需要模型凭据。
  • 控制 UI E2E: pnpm test:ui:e2e 运行 Vitest + Playwright 泳道,通常针对模拟的 Gateway WebSocket。四个资源组保留两个执行阶段:ui-e2e-bundled 和 ui-e2e-standalone 首先运行,总计最多两个 worker;随后 ui-e2e-serial 和 ui-e2e-serial-standalone 共享一个 worker。两个 bundle 消费者会延迟共享一个临时 UI bundle/预览,直到调用关闭。独立项目拥有自己的 fixture、source 或自定义构建服务器;仅选择独立套件可避免共享 bundle 构建。每个选中的项目都会接收 Chromium 元数据,新的 E2E 文件默认采用并行 bundled 所有权。根配置保留完整的发现清单:ui/src/**/*.e2e.test.ts,以及 QA Lab 媒体转录和 OpenClaw-delegation 真实 Gateway 套件。共享 mocks/controls 位于 ui/src/test-helpers/control-ui-e2e.ts。某些套件会启动隔离的真实 Gateway;OPENCLAW_UI_E2E_SKIP_REAL_GATEWAY=1 会排除它们。pnpm test:e2e 包含此泳道,资源组没有额外的 CI 作业。仅当干净的 Linux/浏览器一致性是证明的一部分时,才使用 Testbox/Crabbox。在 linked worktree 中,node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/e2e/chat-flow.messaging.e2e.test.ts 可避免针对目标本地运行进行 pnpm 依赖协调。
  • 控制 UI 真实 Gateway 审批证明: 针对带有 mock provider 的隔离 Gateway,检查默认和显式 Full Access 委托。在运行目标证明之前,先构建运行时:
pnpm build qaRuntime
node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts \
  --configLoader runner extensions/qa-lab/src/control-ui-openclaw-delegation.real-gateway.e2e.test.ts
  • TUI PTY 测试: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts 运行快速的 fake-backend PTY 泳道。OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 或 pnpm tui:pty:test:watch --mode local 运行较慢的 tui --local 冒烟测试,它仅 mock 外部模型端点。CI 还会在构建 dist/ 后设置 OPENCLAW_TUI_PTY_USE_BUILT_CLI=1;仅当 exact-head 构建产物已存在时才使用该标志。请断言稳定的可见文本或 fixture 调用,而不是原始 ANSI 快照。
  • pnpm test:extensions 和 pnpm test extensions 运行所有扩展/插件分片。重量级 channel 插件、浏览器插件和 OpenAI 作为专用分片运行;其他插件组保持批量运行。pnpm test extensions/<id> 运行一个 bundled 插件泳道。
  • 浏览器原生主机: node scripts/run-vitest.mjs extensions/browser/src/browser/extension-install.native-host.e2e.test.ts 在 macOS 或 Linux 上针对已构建的 dist 和合成安装状态运行真实的 native messaging 启动器;它不会启动 Chrome 或 Gateway。Windows 会跳过此 POSIX 进程证明,因为 native bootstrap 在那里使用手动配对。E2E 所有者会在 worker 之前准备产物。对于已构建的候选版本,请在命令前添加前缀 OPENCLAW_E2E_USE_PREBUILT_DIST=1 以复用该版本;缺失的产物会导致测试失败。此用例属于 pnpm test:e2e,不属于浏览器 source 分片或未指定目标的 pnpm test 单元测试套件。Linux CI 会在 build-artifacts 中显式运行它,并验证一个 JSON 报告,以证明确切命名的测试已通过。该工作流仅跳过缺少此测试文件的冻结历史 checkout;该跳过是不可用的证明,而不是通过或覆盖。
  • 具有同级测试的 source 文件会先映射到该同级测试,然后再回退到更宽的目录 glob。对 src/channels/plugins/contracts/test-helpers、src/plugin-sdk/test-helpers 和 src/plugins/contracts 下的 helper 编辑会使用本地 import 图来运行导入它们的测试,而不是在依赖路径精确时广泛运行每个分片。
  • 契约目录目标会扇出到其契约泳道:pnpm test src/channels/plugins/contracts 运行四个 channel 契约配置,pnpm test src/plugins/contracts 运行插件契约配置,因为通用的 channels/plugins 项目排除了 contracts/**。
  • auto-reply 拆分为三个专用配置(core、top-level、reply),以便 reply harness 不会主导更轻量的 top-level status/token/helper 测试。
  • 选中的 plugin-sdk 和 commands 测试文件会通过专用轻量泳道路由,这些泳道仅保留 test/setup.ts,而将运行时重量级用例留在其现有泳道中。
  • 基础 Vitest 配置默认为 pool: "threads" 和 isolate: false,并在整个仓库配置中启用共享的非隔离 runner。
  • pnpm test:channels 运行 vitest.channels.config.ts。

真实 Gateway 控制 UI 夹具生命周期

使用来自 ui/src/test-helpers/control-ui-browser-pairing.ts 的 pairControlUiPage, 配合隔离 Gateway 的 CLI runner,对每个新页面进行身份验证。它会获取 并消费一个全新的 dashboard --json 浏览器交接,并等待 Gateway 握手。Dashboard 配对链接是一次性的;不要将捕获的 URL 复用于另一个标签页或浏览器上下文。将此操作作为 preparePage 传递给 withControlUiRunInspector,以便 collection 对其自己的页面进行身份验证,同时保留 调用方的 Chat 和草稿。重新加载使用浏览器已配对的凭据。

对于真实 Gateway 浏览器 fixture,请使用来自 ui/src/e2e/control-ui-e2e-suite.test-support.ts 的 createControlUiE2eSuite。 suite.define(...) 拥有原生钩子。每个原生 it 都会将其测试上下文传递给 suite.runScenario(context, ...),后者负责获取、测试主体以及在另一个用例开始前的最终化。通过 suite.newBrowserContext 和 suite.closeBrowserContext 获取并关闭浏览器上下文,使延迟获取和 待处理关闭仍由套件拥有。

在 createOpenClawTestState 解析后立即保留测试状态,即使后续配置写入、导入或启动失败也是如此。保留原始启动 Promise, 而不仅仅是它们的超时包装器。在释放状态之前关闭必需的 producer。 对于跨用例共享的 producer(如 MCP 和 auth 套件中那样),使用套件的 resources.run、resources.close 和 resources.release 回调,而不是 独立的 beforeAll/afterAll 清理。资源获取遵循共享 server/browser 获取;teardown 会 join 用例和浏览器清理,关闭 必需的 producer 和 server,并且仅在这些关闭成功后释放状态。

失败或未 join 的清理会保留选择器和状态,阻止使用此套件 owner 的后续用例,并交由原生 Vitest 终止并 join 隔离的 fork。不要 吞掉关闭失败,也不要在未完成的工作下方恢复环境。生命周期 owner 会保留现有的钩子、测试和操作预算。

Gateway 关闭会 join 已接收的 WebSocket 工作和异步连接清理, 包括在其 producer 处通过 trackAsyncWork 注册的协作后台刷新。依赖连接的 worker sidecar 必须在 supervisor transport 或其他依赖关闭之前成功停止;失败会保留这些 依赖并拒绝关闭。注册实际操作,而不仅仅是其 响应或超时包装器;缓存驱逐不会结束其生命周期。withOpenClawTestState 同样 会在释放状态前 join 已注册的回调后代。MCP 请求会观察 调用方取消及其关闭工作 owner,因此关闭会先取消待处理 请求,再 join 处理器并释放 transport。这些作用域不会 自动跟踪任意分离的工作,也不会取代原生测试超时所有权。 其他 Gateway 子系统可以保留有文档记录的有界关闭行为,因此关闭 并不保证所有子系统或后代进程完全静止。

保留的 Control UI 证明

对于启动所有权变更,在浏览器恢复迁移完成之前,执行经过认证的 hello。项目和环境发现可以从 hello 开始;迁移完成不得重新获取这些目录,也不得使已接受的启动失效。将 owner 变更、进程重启和延迟结果 fence 分别覆盖。在重渲染、输入和流式传输期间,按 key 统计存储读取,但不要记录凭据值。将路由 payload 字节数和已加载模块闭包与计时分开比较;CSS 所有权变更还需要保留截图,并在 New session 和 Chat 中执行计算样式或几何检查。

迁移后的 mock 和真实 Gateway 浏览器证明使用新的保留目录。 使用 suite.artifactDir 的场景捕获(包括 Logs 和 Usage)按测试尝试延迟分配;独立捕获按调用分配。MCP 一致性测试和 auth transport 各自在浏览器可用性检查后分配一个套件拥有的目录,即使媒体捕获已禁用。Auth transport 截图会等待有意义的内容以及呈现 owner 的有限入场或调整大小动画,同时永久后代活动继续。 共享的 agent-file 捕获 helper 在启用捕获时按模块求值分配一次,并在该模块的场景间共享该目录。仅 Node 的 createControlUiE2eArtifactDir(scope, parentDir?) helper 位于 ui/src/test-helpers/control-ui-e2e-artifacts.ts,会打印实际分配的路径。 显式父目录优先;否则使用修剪后的现有 OPENCLAW_UI_E2E_ARTIFACT_DIR,然后使用仓库的 .artifacts/control-ui-e2e 父目录。现有功能特定目录控制和脚本输出参数选择父目录,并在其下使用唯一子目录。显式截图文件名 控制会保留 basename 并打印重定位后的路径。

保持捕获 gate 与分配独立:OPENCLAW_CAPTURE_UI_PROOF、 OPENCLAW_UI_E2E_RECORD 和输出存在 gate 保留其现有含义。 对于按尝试捕获,在场景执行期间或 beforeEach 中分配。 向共享捕获 helper 传递相同的 owner,使截图、报告和 video 保持在一起。区分尝试内的阶段名称。在最终化 video 之前关闭浏览器上下文。

聊天加载性能真实 Gateway 套件会在 loading-evidence.json 中记录浏览器时间戳,用于历史请求、数据发布、已提交行 模型和视觉静止。窗格更新在滚动时仍可能显示旧行模型,因此检查会验证保留行的索引前进, 然后再检查 50 ms 内没有 transcript 变更、调整大小或滚动。它会分别记录该安静区间的开始和确认;确认延迟不是应用延迟。非零的 lateChanges 计数会使该静止样本失效。

使用无捕获的普通运行进行延迟比较。当 OPENCLAW_CAPTURE_UI_PROOF=1 时,套件还会保留截图、video 和 history-pagination.cpuprofile。性能分析和捕获会增加开销,并且 CPU profile 包括分页计时器开始前的 profiler 启动。比较同一 fixture 和构建模式的重复运行;将旧测试驱动器的 wall 计时与浏览器时间戳分开。

成功和失败的证据都会被保留。清理是手动的:只删除你拥有且已完成审查的精确目录。切勿在重放前递归删除共享父目录。一次性构建/媒体 fixture 和临时原始 video 有各自的清理。新捕获无法恢复被覆盖的证据;不要将重放描述为恢复丢失的文件。

超时诊断在现有 OPENCLAW_UI_E2E_DIAGNOSTIC_DIR 或默认超时目录之下分配新的子目录。每个子目录将其原始 failure.private.json 报告和捕获的 failure.private.png 截图保存在本地,同时附带一份允许列表中的 failure.public.json 摘要。自动 CI 上传仅匹配 failure-*/failure.public.json;原始报告和截图保持私有。没有公开摘要的旧冻结目标不会产生匹配的上传,也绝不会回退到原始捕获。

共享套件在排空路由并关闭所拥有的浏览器上下文之前捕获原生测试超时。清理和待执行的测试主体加入同一捕获,因此后续的页面已关闭错误不会替换原始的超时证据。

共享失败收集器为渲染器评估和截图捕获提供五秒的预算。如果渲染器停滞,它会记录不完整的诊断并返回,以便调用方可以重新抛出原始失败。预算到期后,迟到的浏览器响应无法发布截图;测试操作截止时间和调用方拥有的浏览器清理保持不变。

来自共享套件 withPage 的页面还会在测试运行前启用渲染器停滞检查。当渲染器错过该读取截止时间时,公开摘要的 rendererStall 按类别记录主线程繁忙时间和暂停的 JavaScript 堆栈,然后在额外的三秒预算内恢复页面。在响应式读取之前已结束的停滞会以至少一秒的帧及其脚本归属出现在 browser.longFrames 中。两者仅保留打包路径、位置、函数名以及监听器标签和事件名称;并使用同一提交的打包构建源映射来映射位置。

私有 JSON 报告的 ci.shardIndex 和 ci.vitestShardCount 字段分别记录由正常 CI 提供的 VITEST_SHARD_INDEX 和 VITEST_SHARD_COUNT。缺失值保持 null;手动和单独发布的 E2E 调用不会从 Vitest 的 --shard 参数推断此元数据。

Mantis 为设置日志、捕获尝试及其报告分配调用目录;构建器保留每次尝试的相对路径,并拒绝覆盖现有报告。

其他输出所有者仍然存在,包括 chat-attachment-read-lifecycle。不要假设未迁移的所有者共享此保留保证。

Chromium 录制期间的截图

会话主机命令状态的真实网关验证使用 page.screenshot({ path }),不带 clip 或 fullPage: true,保持其现有的视口、录制大小、等待和动画选项。此路径已在 Linux 上使用 Playwright 1.62.1 和完整版 Chrome for Testing 151.0.7922.34 验证。

其他录制所有者尚未被此验证迁移或认证;有些仍使用定位器或整页截图。这不是套件级的捕获策略。在更改其捕获模式之前,请验证每个所有者的截图内容和最终视频。使用经验证的视口路径时,请在浏览器外部裁剪任何仅元素的 PNG。裁剪无法从已损坏的录制中恢复缺失的内容。

在 macOS arm64 复现环境(使用 Playwright 1.62.1 及其捆绑的完整版 Chrome for Testing 151.0.7922.34)中,locator.screenshot() 和 page.screenshot({ clip }) 导致了小的屏幕录制帧。该元素出现在视频原点,其他区域为灰色,尽管 PNG、DOM 几何和功能断言均正确。fullPage: true 不是通用的解决方法:大于视口的文档反而可能产生缩小页面和灰色填充。在相同的合成复现中,未裁剪的视口捕获保留了录制内容;其他浏览器版本和平台需要各自的验证。

这是上游捕获限制,而非网关或上下文清理失败。Chromium 的截图处理程序 在捕获期间临时更改共享视图大小并在之后恢复;其屏幕录制生成器可以观察到中间表面。Playwright 的录制器 用灰色填充尺寸过小的帧。关闭上下文会完成视频,但不会修复这些帧。不要过滤掉坏帧或更改 UI 行为来掩盖此限制。

验证每次捕获附近的最终视频内容,而不仅仅是其尺寸或定位器断言的成功与否。对于依赖项升级,使用包含偏移小元素的合成页面进行复现,比较元素、裁剪、视口和超大整页截图,并检查每个解码帧。将真实主机/配置文件的素材保留在本地;在共享前检查公开验证是否仅包含合成内容。正确的 PNG 仍然是有用的静态图像证据,但损坏的视频不能作为连续流程的证据。

网关与 E2E

  • 网关测试包含在未指定目标的 pnpm test 完整套件中;可使用 pnpm test:gateway 单独运行。
  • pnpm test:e2e:仓库 E2E 聚合 = pnpm test:e2e:gateway && pnpm test:e2e:agent-plugin-gateway && pnpm test:ui:e2e。
  • pnpm test:e2e:agent-plugin-gateway:合成提供者和 MCP 测试夹具演练插件安装和真实网关。OPENCLAW_VITEST_RUNTIME=bun 为 OpenClaw 产品进程选择 Bun;测试夹具服务和构建编排保持其现有的 Node 命令。
  • pnpm test:e2e:gateway:网关端到端冒烟测试(多实例 WS/HTTP/节点配对)。在 vitest.e2e.config.ts 中默认为 threads + isolate: false 且使用一个 worker;可通过 OPENCLAW_E2E_WORKERS=<n> 选择并行(上限 16),并通过 OPENCLAW_E2E_VERBOSE=1 启用详细日志。 大规模运行只准备一次共享运行时,然后在全新进程中依次使用四个 Vitest 分片,以限制 worker 内存。worker 限制在每个进程内生效;普通测试失败会被保留,同时其余分片继续完成。显式过滤器、监视模式、调用方提供的分片、覆盖率和报告输出选项保持一次直接调用。
  • pnpm test:live:提供者实时测试(Claude/Minimax/DeepSeek/z.ai 等,由 *.live.test.ts 门控)。需要 API 密钥和 LIVE=1(或 OPENCLAW_LIVE_TEST=1)才能取消跳过;使用 OPENCLAW_LIVE_TEST_QUIET=0 输出详细日志。

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