Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(cua-driver): name the canonical runners and test-ownership rules (#4147)

Francesco Bonacci05757de3a090
diff --git a/AGENTS.md b/AGENTS.md
index 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 Linux
X11 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 releases
Follow 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.md
index 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 -RequireGui
macOS: 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 for
reporting and failure isolation. That is an execution detail; contributors
should 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.md
index 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 runner
This 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 -RequireGui
diff --git a/scripts/ci/README.md b/scripts/ci/README.md
index 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 tier
Use the narrowest useful tier during implementation, then complete the required