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.

ci(cua-driver): add OS-scoped Rust and manual e2e lanes

Francesco Bonacciaa71b01d3c25
diff --git a/.github/workflows/ci-nix-linux.yml b/.github/workflows/ci-nix-linux.yml
new file mode 100644
index 0000000000..611a3b0cbc
--- /dev/null
+++ b/.github/workflows/ci-nix-linux.yml
@@ -0,0 +1,45 @@
+name: "CI: Nix Linux Rust source"
+
+# This is the automatic Nix lane. Desktop-heavy legacy checks live in
+# nix-build.yml and nix-wayland.yml and are maintainer-dispatched instead.
+on:
+ pull_request:
+ paths:
+ - "flake.nix"
+ - "flake.lock"
+ - "nix/cua-driver/package.nix"
+ - "nix/cua-driver/tests/rust-unit.nix"
+ - "libs/cua-driver/rust/**"
+ - ".github/workflows/ci-nix-linux.yml"
+ push:
+ branches: [main]
+ paths:
+ - "flake.nix"
+ - "flake.lock"
+ - "nix/cua-driver/package.nix"
+ - "nix/cua-driver/tests/rust-unit.nix"
+ - "libs/cua-driver/rust/**"
+ - ".github/workflows/ci-nix-linux.yml"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-nix-linux-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ rust-source:
+ name: Nix Linux Rust source check
+ runs-on: ubuntu-latest
+ timeout-minutes: 45
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ - name: Install Nix
+ uses: cachix/install-nix-action@08dcb3a5e62fa31e2da3d490afc4176ef55ecd72 # v30
+ with:
+ extra_nix_config: |
+ experimental-features = nix-command flakes
+ - name: Run source-built Rust check
+ run: nix build .#checks.x86_64-linux.cua-driver-linux-rust-unit --print-build-logs --show-trace
diff --git a/.github/workflows/ci-rust-linux.yml b/.github/workflows/ci-rust-linux.yml
new file mode 100644
index 0000000000..e2d050aa78
--- /dev/null
+++ b/.github/workflows/ci-rust-linux.yml
@@ -0,0 +1,54 @@
+name: "CI: Rust Linux unit"
+
+on:
+ pull_request:
+ paths:
+ - "libs/cua-driver/rust/Cargo.toml"
+ - "libs/cua-driver/rust/Cargo.lock"
+ - "libs/cua-driver/rust/crates/cua-driver/**"
+ - "libs/cua-driver/rust/crates/cua-driver-core/**"
+ - "libs/cua-driver/rust/crates/cua-driver-testkit/**"
+ - "libs/cua-driver/rust/crates/platform-linux/**"
+ - "libs/cua-driver/tests/fixtures/**"
+ - "nix/**"
+ - "flake.nix"
+ - "flake.lock"
+ - ".github/workflows/ci-rust-linux.yml"
+ push:
+ branches: [main]
+ paths:
+ - "libs/cua-driver/rust/**"
+ - "libs/cua-driver/tests/fixtures/**"
+ - "nix/**"
+ - "flake.nix"
+ - "flake.lock"
+ - ".github/workflows/ci-rust-linux.yml"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-rust-linux-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ unit:
+ name: Rust Linux unit and compile
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ - uses: dtolnay/rust-toolchain@stable
+ - uses: Swatinem/rust-cache@9d47c6ad4b02e050fd481d890b2ea34778fd09d6 # v2
+ with:
+ workspaces: "libs/cua-driver/rust -> target"
+ - name: Install Linux build dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y --no-install-recommends \
+ clang pkg-config libdbus-1-dev libpipewire-0.3-dev libspa-0.2-dev \
+ libei-dev libx11-dev libxi-dev libxtst-dev libxext-dev
+ - name: Run Linux Rust tests
+ working-directory: libs/cua-driver/rust
+ run: cargo test -p cua-driver -p cua-driver-core -p cua-driver-testkit -p platform-linux --all-targets --locked
diff --git a/.github/workflows/ci-rust-windows.yml b/.github/workflows/ci-rust-windows.yml
new file mode 100644
index 0000000000..0624002d98
--- /dev/null
+++ b/.github/workflows/ci-rust-windows.yml
@@ -0,0 +1,44 @@
+name: "CI: Rust Windows unit"
+
+on:
+ pull_request:
+ paths:
+ - "libs/cua-driver/rust/Cargo.toml"
+ - "libs/cua-driver/rust/Cargo.lock"
+ - "libs/cua-driver/rust/crates/cua-driver/**"
+ - "libs/cua-driver/rust/crates/cua-driver-core/**"
+ - "libs/cua-driver/rust/crates/cua-driver-testkit/**"
+ - "libs/cua-driver/rust/crates/platform-windows/**"
+ - "libs/cua-driver/rust/crates/cua-driver-uia/**"
+ - "libs/cua-driver/rust/crates/focus-monitor-win/**"
+ - "libs/cua-driver/tests/fixtures/**"
+ - ".github/workflows/ci-rust-windows.yml"
+ push:
+ branches: [main]
+ paths:
+ - "libs/cua-driver/rust/**"
+ - "libs/cua-driver/tests/fixtures/**"
+ - ".github/workflows/ci-rust-windows.yml"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-rust-windows-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ unit:
+ name: Rust Windows unit and compile
+ runs-on: windows-latest
+ timeout-minutes: 30
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ - uses: dtolnay/rust-toolchain@stable
+ - uses: Swatinem/rust-cache@9d47c6ad4b02e050fd481d890b2ea34778fd09d6 # v2
+ with:
+ workspaces: "libs/cua-driver/rust -> target"
+ - name: Run Windows Rust tests
+ working-directory: libs/cua-driver/rust
+ run: cargo test -p cua-driver -p cua-driver-core -p cua-driver-testkit -p platform-windows -p cua-driver-uia -p focus-monitor-win --all-targets --locked
diff --git a/.github/workflows/e2e-rust-linux.yml b/.github/workflows/e2e-rust-linux.yml
new file mode 100644
index 0000000000..4214ccb2ad
--- /dev/null
+++ b/.github/workflows/e2e-rust-linux.yml
@@ -0,0 +1,50 @@
+name: "E2E: Rust Linux interactive"
+
+on:
+ workflow_dispatch:
+ inputs:
+ ref:
+ description: "Commit, branch, or tag to test"
+ required: true
+ default: "main"
+ suite:
+ description: "Rust desktop suite"
+ required: true
+ type: choice
+ options: [shared, modality, all]
+ default: shared
+
+permissions:
+ contents: read
+
+jobs:
+ e2e:
+ name: Linux interactive Rust suite
+ runs-on: ubuntu-latest
+ timeout-minutes: 60
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ ref: ${{ inputs.ref }}
+ - uses: dtolnay/rust-toolchain@stable
+ - name: Install GUI and Rust build dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y --no-install-recommends \
+ xvfb dbus-x11 at-spi2-core openbox python3-gi gir1.2-gtk-3.0 \
+ libgtk-3-dev clang pkg-config libdbus-1-dev libpipewire-0.3-dev \
+ libspa-0.2-dev libei-dev libx11-dev libxi-dev libxtst-dev libxext-dev \
+ libwebkit2gtk-4.1-dev libssl-dev libxdo-dev \
+ libayatana-appindicator3-dev librsvg2-dev
+ - name: Run canonical Rust matrix
+ run: |
+ xvfb-run -a --server-args="-screen 0 1920x1080x24" \
+ dbus-run-session -- bash -lc \
+ "scripts/ci/linux/run-rust-e2e.sh --suite '${{ inputs.suite }}'"
+ - name: Upload logs
+ if: always()
+ uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4
+ with:
+ name: rust-linux-e2e-artifacts
+ path: artifacts/cua-driver/linux
+ if-no-files-found: ignore
diff --git a/.github/workflows/e2e-rust-windows.yml b/.github/workflows/e2e-rust-windows.yml
new file mode 100644
index 0000000000..61930b074c
--- /dev/null
+++ b/.github/workflows/e2e-rust-windows.yml
@@ -0,0 +1,46 @@
+name: "E2E: Rust Windows interactive"
+
+on:
+ workflow_dispatch:
+ inputs:
+ ref:
+ description: "Commit, branch, or tag to test"
+ required: true
+ default: "main"
+ suite:
+ description: "Rust desktop suite"
+ required: true
+ type: choice
+ options: [shared, native, all]
+ default: shared
+ runner:
+ description: "Runner label; use the Azure RDP runner label for VM e2e"
+ required: true
+ default: "windows-latest"
+
+permissions:
+ contents: read
+
+jobs:
+ e2e:
+ name: Windows interactive Rust suite
+ runs-on: ${{ inputs.runner }}
+ timeout-minutes: 90
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ ref: ${{ inputs.ref }}
+ - name: Run from the interactive user session
+ shell: pwsh
+ run: .\scripts\ci\windows\run-rust-e2e.ps1 -Suite ${{ inputs.suite }} -RequireGui
+ - name: Collect logs
+ if: always()
+ shell: pwsh
+ run: .\scripts\ci\windows\collect-artifacts.ps1
+ - name: Upload logs
+ if: always()
+ uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4
+ with:
+ name: rust-windows-e2e-artifacts
+ path: artifacts/cua-driver/windows
+ if-no-files-found: ignore
diff --git a/.github/workflows/nix-build.yml b/.github/workflows/nix-build.yml
index abf1d9264a..8cf029dbaa 100644
--- a/.github/workflows/nix-build.yml
+++ b/.github/workflows/nix-build.yml
@@ -1,21 +1,9 @@
name: Nix Build & Integration Tests
on:
- pull_request:
- paths:
- - 'nix/**'
- - 'flake.nix'
- - 'flake.lock'
- - 'libs/cua-driver/rust/**'
- - '.github/workflows/nix-build.yml'
- push:
- branches: [main]
- paths:
- - 'nix/**'
- - 'flake.nix'
- - 'flake.lock'
- - 'libs/cua-driver/rust/**'
- - '.github/workflows/nix-build.yml'
+ # The legacy GUI/toolkit matrix is expensive and includes GIF diagnostics.
+ # It remains available for maintainers, while ci-nix-linux.yml owns the
+ # automatic source-built Rust check.
workflow_dispatch:
permissions:
diff --git a/.github/workflows/nix-wayland.yml b/.github/workflows/nix-wayland.yml
index a6e7a6addb..e651b513b3 100644
--- a/.github/workflows/nix-wayland.yml
+++ b/.github/workflows/nix-wayland.yml
@@ -4,27 +4,14 @@ name: CUA Driver Native-Wayland TDD Suite
# sessions (XFCE on labwc/sway, plus KDE and GNOME). The cursor-click-gif and
# background-terminal-gif tests use the EIS-backed cua-compositor injection path
# for deterministic keyboard delivery without relying on compositor focus policy.
-# The triggers mirror the X11 nix-build.yml workflow (PRs/pushes touching
-# nix/flake/driver, plus manual dispatch). These jobs are BLOCKING
-# (no continue-on-error): a red cell fails the PR.
+# These jobs are maintainer-dispatched desktop diagnostics. They are BLOCKING
+# within a dispatched run, but do not charge every PR with the full compositor
+# matrix.
# Artifacts (screenshots, GIFs, logs) are uploaded so you can see exactly what
# each compositor does.
on:
- pull_request:
- paths:
- - 'nix/**'
- - 'flake.nix'
- - 'flake.lock'
- - 'libs/cua-driver/rust/**'
- - '.github/workflows/nix-wayland.yml'
- push:
- branches: [main]
- paths:
- - 'nix/**'
- - 'flake.nix'
- - 'flake.lock'
- - 'libs/cua-driver/rust/**'
- - '.github/workflows/nix-wayland.yml'
+ # Native-compositor checks are maintainer-dispatched because they are
+ # desktop e2e coverage, not cheap pull-request unit checks.
workflow_dispatch:
permissions:
diff --git a/flake.nix b/flake.nix
index b15c2103ac..d18f04e733 100644
--- a/flake.nix
+++ b/flake.nix
@@ -49,6 +49,12 @@
checks =
{
cua-driver-build = cuaDriverPackage;
+ # Source-built, headless Rust checks. The desktop behavioral
+ # matrix remains an explicit maintainer-dispatched e2e lane.
+ cua-driver-linux-rust-unit = import ./nix/cua-driver/tests/rust-unit.nix {
+ inherit pkgs;
+ src = rustSrc;
+ };
}
// pkgs.lib.optionalAttrs (system == "x86_64-linux") {
# NixOS container integration test (x86_64-linux only)
diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/lib.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/lib.rs
index 9f213aace0..504eb22c50 100644
--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/lib.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/lib.rs
@@ -24,6 +24,14 @@
//! [`ChildReaper`] kills every spawned child on drop. On Windows it also assigns
//! them to a `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` job, so the OS reaps the whole
//! tree even on panic / SIGKILL / Ctrl-C — no orphaned windows or held ports.
+//!
+//! ## Relocated runners
+//!
+//! The testkit normally discovers the driver and staged apps under the Cargo
+//! workspace. CI runners that build those artifacts in an immutable or remote
+//! workspace can override the paths with `CUA_TEST_DRIVER_BIN`,
+//! `CUA_TEST_APPS_ROOT`, and `CUA_TEST_WORKSPACE_ROOT`. These variables affect
+//! tests only; they are never read by the shipped driver.
pub mod ax;
mod driver;
diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/paths.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/paths.rs
index 33c107d465..1bb58655cb 100644
--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/paths.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/paths.rs
@@ -1,4 +1,5 @@
-//! Filesystem paths, resolved at test runtime from `CARGO_MANIFEST_DIR`.
+//! Filesystem paths, resolved at test runtime from environment overrides or
+//! `CARGO_MANIFEST_DIR`.
//!
//! When an integration test runs, Cargo sets `CARGO_MANIFEST_DIR` to the crate
//! under test (`crates/cua-driver`), so `workspace_root()` resolves the same
@@ -8,6 +9,9 @@ use std::path::PathBuf;
/// The Rust workspace root (`libs/cua-driver/rust`).
pub fn workspace_root() -> PathBuf {
+ if let Some(root) = std::env::var_os("CUA_TEST_WORKSPACE_ROOT") {
+ return PathBuf::from(root);
+ }
let manifest = std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR");
PathBuf::from(manifest)
.parent()
@@ -22,6 +26,9 @@ pub fn workspace_root() -> PathBuf {
/// divergent spellings (and the macOS release-or-debug variant) that were
/// copy-pasted across the test files.
pub fn driver_binary() -> PathBuf {
+ if let Some(path) = std::env::var_os("CUA_TEST_DRIVER_BIN") {
+ return PathBuf::from(path);
+ }
let name = if cfg!(target_os = "windows") {
"cua-driver.exe"
} else {
@@ -39,5 +46,43 @@ pub fn driver_binary() -> PathBuf {
/// `tests/fixtures/build/{windows.ps1,macos.sh}`). Example:
/// `harness_app("harness-wpf", "CuaTestHarness.Wpf.exe")`.
pub fn harness_app(dir: &str, exe: &str) -> PathBuf {
- workspace_root().join("test-apps").join(dir).join(exe)
+ let root = std::env::var_os("CUA_TEST_APPS_ROOT")
+ .map(PathBuf::from)
+ .unwrap_or_else(|| workspace_root().join("test-apps"));
+ root.join(dir).join(exe)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{driver_binary, harness_app, workspace_root};
+ use std::path::PathBuf;
+
+ fn with_env<F>(name: &str, value: &str, test: F)
+ where
+ F: FnOnce(),
+ {
+ let previous = std::env::var_os(name);
+ std::env::set_var(name, value);
+ test();
+ match previous {
+ Some(value) => std::env::set_var(name, value),
+ None => std::env::remove_var(name),
+ }
+ }
+
+ #[test]
+ fn relocated_runner_overrides_are_respected() {
+ with_env("CUA_TEST_WORKSPACE_ROOT", "/tmp/cua-test-workspace", || {
+ assert_eq!(workspace_root(), PathBuf::from("/tmp/cua-test-workspace"));
+ });
+ with_env("CUA_TEST_DRIVER_BIN", "/tmp/cua-driver", || {
+ assert_eq!(driver_binary(), PathBuf::from("/tmp/cua-driver"));
+ });
+ with_env("CUA_TEST_APPS_ROOT", "/tmp/cua-test-apps", || {
+ assert_eq!(
+ harness_app("harness-electron", "CuaTestHarness.Electron"),
+ PathBuf::from("/tmp/cua-test-apps/harness-electron/CuaTestHarness.Electron")
+ );
+ });
+ }
}
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/README.md b/libs/cua-driver/rust/crates/cua-driver/tests/README.md
index 6b59ddba52..39ccad6b9b 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/README.md
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/README.md
@@ -33,6 +33,14 @@ Build harness apps before running ignored tests:
Staged outputs are read from `../../test-apps/harness-<name>/`.
+The canonical cross-platform matrix is
+`cross_platform_behavior_test.rs`. It runs the same external-state scenarios
+against Electron and Tauri on each supported host. CI and VM runners set
+`CUA_TEST_DRIVER_BIN`, `CUA_TEST_APPS_ROOT`, and
+`CUA_TEST_WORKSPACE_ROOT` when artifacts are built outside Cargo's default
+workspace paths. They also set `CUA_TEST_REQUIRE_FIXTURES=1`, turning a missing
+fixture into a failure instead of a silent skip.
+
## Running
```bash
@@ -52,11 +60,11 @@ builds selected Windows harness apps and maps them into the sandbox. The current
Windows GUI validation path should use a real user desktop session through RDP
or an interactive scheduled task.
-Windows GUI modality tests require a foreground interactive desktop where
-`GetForegroundWindow` returns a real user window. SSH-launched commands,
-scheduled tasks, and PsExec-launched commands can enter the right user session
-while still exposing no foreground desktop; those tests self-skip in that state
-because the focus oracle would otherwise report meaningless pid-0 results.
+Windows GUI modality tests require a user desktop where the focus sentinel can
+become the foreground window. SSH-launched commands start in Session 0 and
+cannot drive the user's desktop directly; launch GUI tests through an
+interactive scheduled task (`/IT`) or equivalent so they run in the logged-on
+user session.
The Windows probe distinguishes two no-foreground states:
@@ -71,6 +79,17 @@ The Windows probe distinguishes two no-foreground states:
Set `CUA_REQUIRE_GUI=1` on dedicated GUI runners to turn these desktop
self-skips into hard failures with the full desktop-state diagnostic.
+The repository-level runners are the preferred entrypoints for the canonical
+matrix:
+
+```bash
+scripts/ci/linux/run-rust-e2e.sh --suite shared
+```
+
+```powershell
+.\scripts\ci\windows\run-rust-e2e.ps1 -Suite shared -RequireGui
+```
+
## Optional External Apps
These suites are Rust source-of-truth coverage for real installed apps, but they
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rs
index 8fe7efc889..8da9c79b24 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rs
@@ -127,6 +127,12 @@ struct Fixture {
fn launch_host(spec: &HostSpec) -> Option<Fixture> {
if !spec.path.exists() {
+ if std::env::var_os("CUA_TEST_REQUIRE_FIXTURES").is_some() {
+ panic!(
+ "{} fixture is required but was not staged at {:?}",
+ spec.name, spec.path
+ );
+ }
eprintln!(
"[{}] fixture not staged at {:?}; skipping",
spec.name, spec.path
@@ -134,7 +140,12 @@ fn launch_host(spec: &HostSpec) -> Option<Fixture> {
return None;
}
- let mut driver = spawn_driver()?;
+ let Some(mut driver) = spawn_driver() else {
+ if std::env::var_os("CUA_TEST_REQUIRE_FIXTURES").is_some() {
+ panic!("cua-driver could not be started for the required {} fixture", spec.name);
+ }
+ return None;
+ };
let mut command = Command::new(&spec.path);
command
.args(&spec.args)
diff --git a/nix/cua-driver/README.md b/nix/cua-driver/README.md
new file mode 100644
index 0000000000..649a5a7490
--- /dev/null
+++ b/nix/cua-driver/README.md
@@ -0,0 +1,37 @@
+# Linux driver checks
+
+Nix is the Linux test environment. It is used for reproducible builds and for
+containerized or compositor-backed Linux checks; Windows and macOS checks do
+not belong here.
+
+## Check tiers
+
+| Tier | Check family | Trigger | Evidence |
+| --- | --- | --- | --- |
+| Source | `cua-driver-linux-rust-unit` | Linux Rust/Nix changes | Cargo unit tests and compilation |
+| Contract | `cua-driver-integration`, `cua-driver-set-config`, `cua-driver-screenshot` | Maintainer or Linux CI | service, config, and capture assertions |
+| Behavioral | `e2e-rust-linux` and the shared Rust matrix | Manual maintainer dispatch | external app state, AX trees, logs, failure screenshots |
+| Supporting | legacy background GUI and compatibility checks | Explicitly selected | toolkit-specific diagnostics |
+
+The behavioral matrix is owned by
+`libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rs`.
+Nix checks must not create a second scenario list in Nix expressions.
+
+The current automatic Nix lane builds the driver and Rust workspace from source.
+The manual Linux desktop runner builds Electron/Tauri from the repo-local
+fixture sources in the desktop session. Moving those app builds fully inside
+Nix requires committing and hashing their dependency lockfiles, especially the
+Electron npm graph, and is intentionally a follow-up rather than an opaque
+prebuilt download.
+
+## Naming and artifacts
+
+Use `cua-driver-linux-<surface>-<scenario>` for new checks. Do not add `gif`
+to new check names. A failing behavioral check should retain structured output,
+the driver log, an AX/UIA tree where available, and a PNG when the scenario is
+pixel-based. GIF recorders remain legacy supporting diagnostics until their
+behavior is covered by the Rust matrix.
+
+The old `linux-background-gui.nix` and compositor matrix are not deleted in one
+step. They contain useful toolkit and regression evidence, but read-only
+skeleton entries must not be reported as equivalent to a passing user workflow.
diff --git a/nix/cua-driver/tests/README.md b/nix/cua-driver/tests/README.md
new file mode 100644
index 0000000000..f1b8a59c35
--- /dev/null
+++ b/nix/cua-driver/tests/README.md
@@ -0,0 +1,17 @@
+# Linux Nix test layout
+
+Nix expressions are grouped by what they prove:
+
+| Path | Role |
+| --- | --- |
+| `rust-unit.nix` | Source-built Rust workspace checks without a desktop session |
+| `integration.nix` | Driver service starts and answers protocol requests |
+| `set-config.nix` | Configuration persistence contract |
+| `screenshot.nix` | Capture contract in a managed display |
+| `wayland/` | Compositor-specific supporting and red/green checks |
+| `linux-background-gui.nix` | Legacy toolkit matrix, supporting coverage only |
+| `linux-*-gif.nix` | Legacy visual diagnostics, never the canonical Rust matrix |
+
+New user-behavior coverage belongs in the Rust test harness first. A Nix check
+may provide the session and package environment, but it should invoke the
+shared Rust scenario or clearly identify itself as supporting coverage.
diff --git a/nix/cua-driver/tests/rust-unit.nix b/nix/cua-driver/tests/rust-unit.nix
new file mode 100644
index 0000000000..4764783691
--- /dev/null
+++ b/nix/cua-driver/tests/rust-unit.nix
@@ -0,0 +1,51 @@
+# Source-built Linux Rust unit/compile checks.
+#
+# This is intentionally separate from package.nix: the shipped daemon package
+# must remain display-independent, while this check validates the Rust source
+# and testkit in Nix's reproducible build environment.
+{
+ pkgs,
+ src,
+ ...
+}:
+
+pkgs.rustPlatform.buildRustPackage {
+ pname = "cua-driver-rust-unit-tests";
+ version = (pkgs.lib.importTOML "${src}/Cargo.toml").workspace.package.version;
+ inherit src;
+
+ cargoLock.lockFile = "${src}/Cargo.lock";
+ cargoTestFlags = [
+ "-p"
+ "cua-driver"
+ "-p"
+ "cua-driver-core"
+ "-p"
+ "cua-driver-testkit"
+ "-p"
+ "platform-linux"
+ "--all-targets"
+ ];
+
+ nativeBuildInputs = with pkgs; [
+ pkg-config
+ rustPlatform.bindgenHook
+ clang
+ ];
+ buildInputs = with pkgs; [
+ libx11
+ libxi
+ libxtst
+ libxext
+ pipewire
+ libei
+ ];
+
+ # The default Cargo test set is deliberately headless. The ignored desktop
+ # matrix is run by the manual Linux e2e workflow and is not hidden in Nix.
+ doCheck = true;
+
+ installPhase = ''
+ touch $out
+ '';
+}
diff --git a/scripts/ci/README.md b/scripts/ci/README.md
new file mode 100644
index 0000000000..2e2bfa2a2a
--- /dev/null
+++ b/scripts/ci/README.md
@@ -0,0 +1,15 @@
+# Cua-driver CI runners
+
+These scripts are thin entrypoints around the Rust integration tests. They
+build the repo-local fixture applications on demand, set the testkit path
+overrides, and collect logs. They do not push code or alter branches.
+
+| Runner | Session | Canonical command |
+| --- | --- | --- |
+| `linux/run-rust-e2e.sh` | Linux X11/Wayland desktop | `--suite shared` |
+| `windows/run-rust-e2e.ps1` | Windows console/RDP user session | `-Suite shared -RequireGui` |
+
+The Windows workflow accepts a runner label so the same command can execute on
+the Azure VM's active-RDP runner when that self-hosted label is configured. A
+GitHub-hosted Windows runner is useful for smoke validation, but it is not a
+substitute for the Azure user-session run.
diff --git a/scripts/ci/linux/run-rust-e2e.sh b/scripts/ci/linux/run-rust-e2e.sh
new file mode 100755
index 0000000000..d90c021fa5
--- /dev/null
+++ b/scripts/ci/linux/run-rust-e2e.sh
@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Run the canonical Rust desktop matrix on a Linux user session.
+# Scenario definitions and assertions live in the Rust integration test.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+DRIVER_ROOT="${REPO_ROOT}/libs/cua-driver"
+RUST_ROOT="${DRIVER_ROOT}/rust"
+BUILD_FIXTURES=1
+SUITE="shared"
+
+usage() {
+ cat <<'EOF'
+Usage: run-rust-e2e.sh [--no-build] [--suite shared|modality|all]
+
+The caller must provide a real or virtual Linux desktop session. For a
+headless session, wrap this command in xvfb-run and dbus-run-session.
+EOF
+}
+
+while (($#)); do
+ case "$1" in
+ --no-build) BUILD_FIXTURES=0 ;;
+ --suite) SUITE="${2:?missing suite}"; shift ;;
+ -h|--help) usage; exit 0 ;;
+ *) echo "unknown argument: $1" >&2; usage >&2; exit 2 ;;
+ esac
+ shift
+done
+
+case "$SUITE" in
+ shared|modality|all) ;;
+ *) echo "unsupported suite: $SUITE" >&2; exit 2 ;;
+esac
+
+mkdir -p "${REPO_ROOT}/artifacts/cua-driver/linux"
+export CUA_TEST_WORKSPACE_ROOT="${RUST_ROOT}"
+export CUA_TEST_DRIVER_BIN="${RUST_ROOT}/target/release/cua-driver"
+export CUA_TEST_APPS_ROOT="${RUST_ROOT}/test-apps"
+export CUA_TEST_REQUIRE_FIXTURES=1
+export CUA_TEST_DRIVER_STDERR=1
+
+if [[ "${BUILD_FIXTURES}" == 1 ]]; then
+ cargo build --release -p cua-driver --manifest-path "${RUST_ROOT}/Cargo.toml"
+ bash "${DRIVER_ROOT}/tests/fixtures/build/linux.sh"
+fi
+
+if [[ ! -x "${CUA_TEST_DRIVER_BIN}" ]]; then
+ echo "driver binary not found: ${CUA_TEST_DRIVER_BIN}" >&2
+ exit 1
+fi
+if [[ ! -x "${CUA_TEST_APPS_ROOT}/harness-electron/CuaTestHarness.Electron" ]]; then
+ echo "Electron fixture was not built: ${CUA_TEST_APPS_ROOT}/harness-electron" >&2
+ exit 1
+fi
+
+run_test() {
+ local name="$1"
+ shift
+ echo "[RUN] ${name}"
+ (cd "${RUST_ROOT}" && "$@") 2>&1 | tee "${REPO_ROOT}/artifacts/cua-driver/linux/${name}.log"
+}
+
+if [[ "${SUITE}" == shared || "${SUITE}" == all ]]; then
+ run_test shared-behavior-matrix \
+ cargo test -p cua-driver --test cross_platform_behavior_test -- \
+ --ignored --nocapture --test-threads=1
+fi
+
+if [[ "${SUITE}" == modality || "${SUITE}" == all ]]; then
+ run_test modality-capture \
+ cargo test -p cua-driver --test modality_capture_mode_test -- \
+ --ignored --nocapture --test-threads=1
+ run_test modality-desktop-scope \
+ cargo test -p cua-driver --test modality_desktop_scope_linux_test -- \
+ --ignored --nocapture --test-threads=1
+fi
+
+echo "Linux Rust e2e suite completed: ${SUITE}"
diff --git a/scripts/ci/windows/build-harnesses.ps1 b/scripts/ci/windows/build-harnesses.ps1
new file mode 100644
index 0000000000..0db8d1eb03
--- /dev/null
+++ b/scripts/ci/windows/build-harnesses.ps1
@@ -0,0 +1,16 @@
+# Build all repo-local Windows harness apps from source.
+param(
+ [ValidateSet("none", "wpf", "winui3", "webview", "electron", "tauri")]
+ [string]$Skip = "none"
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = (Resolve-Path (Join-Path $scriptDir "..\..\..")).Path
+$fixtureBuild = Join-Path $repoRoot "libs\cua-driver\tests\fixtures\build\windows.ps1"
+
+& $fixtureBuild -Skip $Skip
+if ($LASTEXITCODE -ne 0) {
+ throw "Windows harness build failed with exit code $LASTEXITCODE"
+}
diff --git a/scripts/ci/windows/collect-artifacts.ps1 b/scripts/ci/windows/collect-artifacts.ps1
new file mode 100644
index 0000000000..6e99b44b1b
--- /dev/null
+++ b/scripts/ci/windows/collect-artifacts.ps1
@@ -0,0 +1,19 @@
+param(
+ [string]$OutputDirectory = "artifacts\cua-driver\windows"
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = (Resolve-Path (Join-Path $scriptDir "..\..\..")).Path
+$destination = Join-Path $repoRoot $OutputDirectory
+New-Item -ItemType Directory -Force $destination | Out-Null
+
+$rustRoot = Join-Path $repoRoot "libs\cua-driver\rust"
+$target = Join-Path $rustRoot "target"
+if (Test-Path $target) {
+ Get-ChildItem -Path $target -Filter "*.log" -Recurse -ErrorAction SilentlyContinue |
+ Copy-Item -Destination $destination -Force
+}
+
+Write-Host "Collected Windows driver artifacts in $destination" -ForegroundColor Green
diff --git a/scripts/ci/windows/run-rust-e2e.ps1 b/scripts/ci/windows/run-rust-e2e.ps1
new file mode 100644
index 0000000000..dc77c89e32
--- /dev/null
+++ b/scripts/ci/windows/run-rust-e2e.ps1
@@ -0,0 +1,78 @@
+# Run the canonical Rust desktop matrix in an active Windows user session.
+# Scenario definitions and assertions stay in the Rust integration test.
+param(
+ [switch]$NoBuild,
+ [ValidateSet("shared", "native", "all")]
+ [string]$Suite = "shared",
+ [switch]$RequireGui
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = (Resolve-Path (Join-Path $scriptDir "..\..\..")).Path
+$driverRoot = Join-Path $repoRoot "libs\cua-driver"
+$rustRoot = Join-Path $driverRoot "rust"
+$artifactDir = Join-Path $repoRoot "artifacts\cua-driver\windows"
+New-Item -ItemType Directory -Force $artifactDir | Out-Null
+
+& (Join-Path $scriptDir "verify-user-session.ps1")
+if ($RequireGui) { $env:CUA_REQUIRE_GUI = "1" }
+
+$env:CUA_TEST_WORKSPACE_ROOT = $rustRoot
+$env:CUA_TEST_DRIVER_BIN = Join-Path $rustRoot "target\release\cua-driver.exe"
+$env:CUA_TEST_APPS_ROOT = Join-Path $rustRoot "test-apps"
+$env:CUA_TEST_REQUIRE_FIXTURES = "1"
+$env:CUA_TEST_DRIVER_STDERR = "1"
+
+if (-not $NoBuild) {
+ & cargo build --release -p cua-driver --manifest-path (Join-Path $rustRoot "Cargo.toml")
+ if ($LASTEXITCODE -ne 0) { throw "Rust driver build failed" }
+ & (Join-Path $scriptDir "build-harnesses.ps1")
+}
+
+if (-not (Test-Path $env:CUA_TEST_DRIVER_BIN)) {
+ throw "Driver binary not found: $($env:CUA_TEST_DRIVER_BIN)"
+}
+foreach ($fixture in @(
+ (Join-Path $env:CUA_TEST_APPS_ROOT "harness-electron\CuaTestHarness.Electron.exe"),
+ (Join-Path $env:CUA_TEST_APPS_ROOT "harness-tauri\CuaTestHarness.Tauri.exe")
+)) {
+ if (-not (Test-Path $fixture)) { throw "Required fixture was not built: $fixture" }
+}
+
+function Invoke-CargoTest {
+ param([string]$Name, [string[]]$Arguments)
+ Write-Host "[RUN] $Name" -ForegroundColor Yellow
+ Push-Location $rustRoot
+ try {
+ $logPath = Join-Path $artifactDir ("$($Name -replace '[^A-Za-z0-9_.-]', '-')}.log")
+ $output = & cargo @Arguments 2>&1
+ $exitCode = $LASTEXITCODE
+ $output | Tee-Object -FilePath $logPath
+ if ($exitCode -ne 0) { throw "$Name failed with exit code $exitCode" }
+ } finally {
+ Pop-Location
+ }
+}
+
+if ($Suite -in @("shared", "all")) {
+ Invoke-CargoTest "shared behavior matrix" @(
+ "test", "-p", "cua-driver", "--test", "cross_platform_behavior_test", "--",
+ "--ignored", "--nocapture", "--test-threads=1"
+ )
+}
+
+if ($Suite -in @("native", "all")) {
+ Invoke-CargoTest "Windows native harnesses" @(
+ "test", "-p", "cua-driver", "--test", "harness_wpf_test", "--",
+ "--ignored", "--nocapture", "--test-threads=1"
+ )
+ Invoke-CargoTest "Windows web harnesses" @(
+ "test", "-p", "cua-driver", "--test", "harness_web_test", "--",
+ "--ignored", "--nocapture", "--test-threads=1"
+ )
+}
+
+Write-Host "Windows Rust e2e suite completed: $Suite" -ForegroundColor Green
diff --git a/scripts/ci/windows/verify-user-session.ps1 b/scripts/ci/windows/verify-user-session.ps1
new file mode 100644
index 0000000000..e9161aee16
--- /dev/null
+++ b/scripts/ci/windows/verify-user-session.ps1
@@ -0,0 +1,11 @@
+# Verify that the runner is inside an interactive user session, not Session 0.
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$sessionId = (Get-Process -Id $PID).SessionId
+if ($sessionId -eq 0) {
+ throw "The test runner is in Session 0. Start it from the active console/RDP user session."
+}
+
+$sessionName = if ($env:SESSIONNAME) { $env:SESSIONNAME } else { "unknown" }
+Write-Host "Interactive Windows session verified: id=$sessionId name=$sessionName" -ForegroundColor Green