Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
docs(cua-driver): name the canonical runners and test-ownership rules (#4147)
Francesco Bonacci05757de3a090
diff --git a/AGENTS.md b/AGENTS.mdindex e1a9065973..583c3dfddf 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -87,6 +87,27 @@ environment prerequisites, and evidence authority.Do not assume that GitHub-hosted Windows runs in Session 0. Keep the hosted LinuxX11 gate, Nix source checks, and compositor-specific Wayland lanes separate.+## Cua Driver test ownership++These rules come from the #4094 test audit.++- Give each contract one owner test, at the strongest boundary that can+ observe it. Delete weaker duplicates instead of keeping parallel copies.+- Do not add test-only switches, environment hooks, or injectors to shipped+ code. Test through the public interface or a real seam.+- Plain `cargo test` must be hermetic: no real input, clipboard, window, or+ per-user host state. Use the testkit's isolated home. Clipboard round trips+ need an explicit `CUA_TEST_ALLOW_CLIPBOARD=1` opt-in.+- Put desktop-bound suites in `cua-driver-e2e` or mark them `#[ignore]`. A+ canonical runner must select every ignored test, or+ `libs/cua-driver/tests/manual-e2e-allowlist.txt` must list it with a reason;+ `.github/scripts/tests/test_cua_driver_e2e_inventory.py` enforces this.+- CI runs whole crates or test binaries, not hand-maintained module filters,+ so a new test module cannot be silently left out.+- A negative test asserts the exact refusal code or error, not just failure.+- When pruning or merging tests, mutation-check the keeper: break the+ behavior and confirm the remaining test fails.+## Pull request titles and component releasesFollow the [release-title rules](CONTRIBUTING.md#agent-assisted-contributions)diff --git a/libs/cua-driver/docs/test-harnesses-guide.md b/libs/cua-driver/docs/test-harnesses-guide.mdindex 9c2597c99c..94d79f39cd 100644--- a/libs/cua-driver/docs/test-harnesses-guide.md+++ b/libs/cua-driver/docs/test-harnesses-guide.md@@ -26,6 +26,11 @@ Windows: .\scripts\ci\windows\run-rust-e2e.ps1 -RequireGuimacOS: libs/cua-driver/tests/runners/macos-lume/run-all.sh```+[`scripts/ci/README.md`](../../../scripts/ci/README.md#canonical-and-supporting-runners)+lists every runner as canonical, scoped, or supporting. The Windows convenience+wrapper in `tests/runners/windows/` and the legacy `tests/runners/windows-sandbox/`+runner are supporting runners, not canonical entrypoints.+The OS workflow may fan the complete matrix out into independent jobs forreporting and failure isolation. That is an execution detail; contributorsshould think of it as one canonical suite.diff --git a/libs/cua-driver/tests/runners/windows/README.md b/libs/cua-driver/tests/runners/windows/README.mdindex c6deddc12e..0d86ca4c16 100644--- a/libs/cua-driver/tests/runners/windows/README.md+++ b/libs/cua-driver/tests/runners/windows/README.md@@ -1,7 +1,9 @@# Windows Rust runnerThis directory keeps a local convenience wrapper for an interactive user-desktop. From the repository root, the canonical command is:+desktop. It is a supporting runner, not a canonical entrypoint; see+[`scripts/ci/README.md`](../../../../../scripts/ci/README.md#canonical-and-supporting-runners).+From the repository root, the canonical command is:```powershell.\scripts\ci\windows\run-rust-e2e.ps1 -RequireGuidiff --git a/scripts/ci/README.md b/scripts/ci/README.mdindex eed53c12ca..b5d14b0738 100644--- a/scripts/ci/README.md+++ b/scripts/ci/README.md@@ -107,6 +107,35 @@ desktop certification, and it does not replace the desktop matrix.## Desktop runners+### Canonical and supporting runners++This table lists every desktop runner and its evidence authority. Only a+canonical runner, run in full at the exact source SHA, certifies desktop+behavior. A scoped gate certifies only its own scope and does not replace+the three OS rows. Supporting runners help with diagnosis or convenience and+never certify.++| Runner | Workflow or environment | Authority |+| --- | --- | --- |+| `scripts/ci/linux/run-rust-e2e.sh` | `e2e-rust-linux.yml`, GitHub-hosted X11 | Canonical: Linux |+| `scripts/ci/windows/run-rust-e2e.ps1 -RequireGui` | `e2e-rust-windows.yml`, GitHub-hosted, when its strict desktop preflight passes | Canonical: Windows |+| `libs/cua-driver/tests/runners/macos-lume/run-all.sh` | Logged-in, TCC-authorized Lume worker; every complete run includes the standalone-browser matrix | Canonical: macOS |+| `scripts/ci/macos/run-rust-e2e.sh` | Called by the Lume wrapper and the hosted macOS script | Matrix implementation behind the macOS rows; refuses to run without the wrapper's unrestricted daemon |+| `scripts/ci/run-rust-standalone-browser-e2e.sh`, `scripts/ci/windows/run-rust-standalone-browser-e2e.ps1` | `e2e-rust-standalone-browsers.yml`; the macOS Lume wrapper runs it as well | Scoped gate: installed Chrome and Edge, required for browser-facing changes |+| `scripts/ci/linux/run-rust-e2e-wayland.sh`, `run-rust-e2e-inject.sh` | `e2e-rust-linux-wayland.yml` (`sway`, `sway-xwayland`, `cua-compositor`) | Scoped gate: native Wayland compositor lanes, kept separate from X11 |+| `run-rust-e2e.sh` in a native Hyprland desktop, plus the allowlisted `hyprland_*` rows | Maintainer's prepared native Hyprland desktop | Scoped gate: native Hyprland; no automated lane |+| `scripts/ci/macos/run-hosted-rust-e2e.sh` | `e2e-rust-macos.yml` with `mode=hosted` | Supporting: supplemental hosted macOS matrix; does not replace Lume |+| `scripts/ci/linux/run-rust-e2e-desktop.sh` | Representative GNOME or KDE maintainer desktop | Supporting: environment coverage |+| `libs/cua-driver/tests/runners/windows/run-all.ps1` | Local RDP or console session | Supporting: convenience wrapper that calls the canonical Windows runner; certify through the canonical row |+| `libs/cua-driver/tests/runners/windows-sandbox/` | Windows Sandbox | Supporting: legacy local smoke; never certifies |+| Azure RDP replay of the Windows runner | Maintainer Azure VM | Supporting: optional environment-parity replay, or a fallback when the hosted preflight cannot prove a capability |+| `scripts/ci/linux/run-valgrind-e2e.py` | `ci-cua-driver-valgrind.yml` | Supporting: memory-safety diagnostic |+| `scripts/ci/linux/preflight-rust-e2e.sh`, `scripts/ci/windows/preflight-rust-e2e.ps1` | `ci-cua-driver-preflight.yml` or a local desktop | Supporting: lightweight host readiness only |+| One-off app smokes and manual recordings | Any | Supporting: diagnostics only |++Nix source checks (`ci-nix-linux.yml`) are a separate build and unit gate,+not a desktop runner.+### Choose the evidence tierUse the narrowest useful tier during implementation, then complete the required