1. Skill Overview
This skill applies to changes to the Control UI that require validation via real browser workflows paired with deterministic mocked Gateway data. It simulates complete end-user interaction journeys — from application bootstrapping and Gateway handshakes to request dispatch and UI state transitions — delivering trustworthy end-to-end verification.
Core Principle: Maintain fully deterministic test scenarios. Never use real provider API keys, live channel credentials, or production Gateway instances unless the user explicitly requests live real-world proof runs.
2. Core Capabilities
2.1 Test Structure
- Full GUI end-to-end test suites live under
ui/src/**/*.e2e.test.ts - The helper file
ui/src/test-helpers/control-ui-e2e.tsboots the Vite-powered Control UI and injects a mocked Gateway WebSocket backend - Narrow rendering logic is prioritized for lightweight
*.browser.test.tsor unit tests; E2E tests are reserved for combined validation of routing, app initialization, Gateway handshake logic, outbound requests, and visible user-facing UI behavior
2.2 Execution Commands
Single isolated E2E test execution (within a 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.tsRun full local UI E2E suite:
pnpm test:ui:e2e
Dependency resolution guidance: Run
pnpm install once inside the Codex worktree when dependencies are missing. For broad GUI validation or heavy dependency-heavy test suites, offload execution to Testbox / Crabbox rather than running full local pnpm test pipelines.2.3 Visual Proof Capture
Visual proof artifacts are generated by default when validating user-facing functionality via the mocked Control UI / dashboard, unless the user explicitly opts out of media capture.
Standard workflow rules:
- Enforce deterministic Vitest E2E assertions; never commit captured screenshots or video recordings to source control
- Launch the mocked Control UI application concurrently with or immediately after E2E test runs:
pnpm dev:ui:mock -- --port . - Utilize Playwright to drive Chromium against the local mock server URL, capturing video and screenshots for every meaningful UI state transition
- Leverage Playwright APIs:
browser.newContext({ recordVideo: { dir, size }, viewport })andpage.screenshot({ path }); output full video file paths before closing the browser context - All artifacts are written to
.artifacts/control-ui-e2e/; absolute file paths are included in the final test summary report
Key guiding rules for visual capture:
- Treat recordings as formal validation evidence, not merely demo footage
- If capture fails or unexpected UI behavior surfaces, halt execution, remediate the underlying functional defect, add or update regression test coverage, then re-run capture
- If visual proof generation is blocked, clearly state the exact blocking root cause while still outputting all text-based E2E validation results
2.4 Mock Gateway Integration Mode
Boot the local UI server, inject mocked Gateway logic prior to page navigation, and assert both mocked Gateway traffic and rendered UI state simultaneously:
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();
Extend typed scenario configuration and response handlers via
installMockGateway to support new Gateway API surface endpoints as required.2.5 Standalone Recording Workflow
For capturing footage against an already running mocked Control UI instance, execute a dedicated temporary Playwright script or Playwright test spec to keep capture logic focused:
- Navigate to the mock server URL
- Interact with UI elements using stable
data-*attribute selectors or accessibility role selectors - Wait for explicit state assertions rather than hardcoded static sleep timers
- For request-driven workflows, assert both visible UI state and mocked Gateway network traffic concurrently
- Insert minimal short sleep intervals only after assertions to ensure readable recorded video playback
- All output video files are stored under
.artifacts/control-ui-e2e/and excluded from version control
3. Primary Use Cases
- End-to-end validation for Control UI code changes
Validate holistic browser-side behavior after modifying Control UI routing, application bootstrapping, Gateway handshake logic, or request/response pipelines.
- Visual regression testing
Generate standardized screenshots and video evidence for user-facing feature changes to enable side-by-side visual comparison during PR reviews.
- Mocked Gateway communication validation
Verify complete bidirectional communication flows between the frontend UI and Gateway without relying on live production Gateway infrastructure.
- Browser-based proof for pull request reviews
Provide replayable browser capture artifacts as objective validation evidence within PR threads, replacing purely textual written descriptions.
- Debugging Control UI interaction defects
Pinpoint exact interaction sequences and state shift root causes for anomalous UI behavior via recorded video footage.
4. Critical Guiding Principles
- Strict determinism: No live provider keys, channel credentials, or production Gateway instances are permitted
- Visual proof generation is enabled by default; only disabled upon explicit user opt-out
- Artifact exclusion rule: Screenshots and video recordings are never committed to the source repository
- Capture equals validation: If recording fails or exposes unexpected behavior, resolve functional defects before re-running capture pipelines
- Dual assertion standard: For request-driven workflows, validate both rendered UI state and mocked Gateway network traffic simultaneously
- Stable selector priority: Use persistent
data-*attributes or accessibility role selectors; avoid reliance on arbitrary fixed sleep timers
Summary
Control UI E2E is a dedicated end-to-end testing skill for OpenClaw’s graphical Control UI dashboard. It leverages Vitest paired with Playwright to run automated tests inside real Chromium browser instances, covering mocked Gateway WebSocket communication, dashboard runtime execution, screenshot and video capture, and full user interaction flows. Visual proof artifacts are generated by default as standardized validation evidence, making this skill the primary tool for Control UI regression testing, pull request audit evidence, and interactive UI defect debugging.
