一、技能概述
该技能适用于 Control UI 相关的变更，这些变更需要通过真实的浏览器流程配合确定性的 Gateway 数据进行验证。它能够模拟完整的用户交互路径，从应用启动、Gateway 握手到请求发送和 UI 状态变化，提供端到端的可信验证。
核心原则：保持场景确定性，不使用真实的 provider 密钥、真实的通道凭证或真实的 Gateway，除非用户明确要求实时证明。
二、核心功能
1. 测试结构
-
使用
ui/src/**/*.e2e.test.ts编写完整的 GUI 流程测试 -
使用
ui/src/test-helpers/control-ui-e2e.ts启动 Vite Control UI 并安装模拟的 Gateway WebSocket -
优先使用现有的
*.browser.test.ts或单元测试处理窄化的渲染逻辑；E2E 测试用于覆盖路由、应用启动、Gateway 握手、请求和可见 UI 行为的组合证明
2. 运行命令
针对单个 E2E 测试（在 Codex worktree 中）：
node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts运行完整本地测试：
pnpm test:ui:e2e依赖缺失时：在 Codex worktree 中执行 pnpm install 安装一次；对于广泛的 GUI 证明或依赖密集型检查，使用 Testbox/Crabbox 而非在本地运行完整的 pnpm 测试。
3. 可视化证明（Visual Proof）
运行模拟 Control UI/仪表盘验证以支持用户可见功能时，默认生成可视化证明，除非用户明确选择退出。
工作流程：
-
保持 Vitest E2E 断言确定性；不提交生成的截图或视频
-
E2E 测试之后或同时，运行模拟 Control UI 应用：
pnpm dev:ui:mock -- --port . -
使用 Playwright 驱动 Chromium 访问本地模拟 URL，为每个有意义的状态捕获视频和截图
-
使用
browser.newContext({ recordVideo: { dir, size }, viewport })、page.screenshot({ path })，并在关闭上下文前报告视频路径 -
产物放在
.artifacts/control-ui-e2e/下，在最终回答中报告绝对路径
重要原则：
-
将录制视为验证，而非仅演示捕获
-
如果录制器失败或显示意外行为，停止、修复行为、添加或更新回归测试，然后重新录制
-
如果可视化证明被阻塞，陈述确切的阻塞原因，并仍报告文本 E2E 证据
4. Mock 模式
启动应用服务器，在 page.goto 之前安装 mock，然后同时断言 Gateway 流量和可见 UI：
const server = await startControlUiE2eServer();
const page = await context.newPage();
const gateway = await installMockGateway(page, {
historyMessages: [{ role: "assistant", content: [{ type: "text", text: "Ready." }] }],
});
await page.goto(`${server.baseUrl}chat`);
await page.locator(".agent-chat__composer-combobox textarea").fill("hello");
await page.getByRole("button", { name: "Send message" }).click();
const request = await gateway.waitForRequest("chat.send");
await gateway.emitChatFinal({ runId: String(request.params.idempotencyKey), text: "Done." });
await page.getByText("Done.").waitFor();通过 installMockGateway 扩展类型化的场景选项或方法响应，以支持新的 Gateway 表面需求。
5. 独立录制（Standalone Recording）
当需要对已运行的模拟 Control UI URL 进行录制时，使用临时 Playwright 脚本或 playwright test spec，保持录制流程聚焦：
-
打开模拟 URL，通过稳定的
data-*选择器或面向用户角色的选择器进行交互，等待断言的状态而非依赖固定 sleep -
同时断言可见 UI 状态和模拟 Gateway 流量（针对请求驱动的流程）
-
仅在断言后使用短 sleep，使录制的视频可读
-
生成的视频存放在
.artifacts/control-ui-e2e/下，不提交
三、主要用途
-
Control UI 变更的端到端验证
当修改了 Control UI 的路由、应用启动、Gateway 握手或请求/响应流程时，通过真实浏览器环境验证整体行为。 -
可视化回归测试
为面向用户的功能变更生成截图和视频证据，供 PR 审查时直观对比。 -
模拟 Gateway 通信测试
在不依赖真实 Gateway 的情况下，通过 mock 验证 UI 与 Gateway 之间的完整通信链路。 -
PR 审查中的浏览器证明
在 PR 中提供可代理验证的浏览器录制证据，替代纯文本描述。 -
调试 Control UI 交互问题
当发现 UI 行为异常时，通过录制视频定位具体的交互步骤和状态变化。
四、重要原则
-
保持确定性：不使用真实的 provider 密钥、通道凭证或真实 Gateway
-
默认生成可视化证明：除非用户明确选择退出
-
不提交产物：截图和视频不提交到仓库
-
录制即验证：如果录制失败或行为异常，先修复再重新录制
-
同时断言 UI 和流量：对请求驱动的流程，同时验证可见 UI 状态和模拟 Gateway 流量
-
优先使用选择器：使用稳定的
data-*选择器或角色选择器，避免依赖固定 sleep
总结：Control UI E2E 是 OpenClaw Control UI 图形界面的端到端测试技能，通过 Vitest + Playwright 在真实浏览器中执行自动化测试，覆盖模拟 Gateway WebSocket、仪表盘运行、截图/录屏等完整流程。它默认生成可视化证明作为验证手段，适用于 Control UI 变更的回归测试、PR 审查和交互问题调试场景。
