Development

Source layout, harnesses, and test entry points for contributors working on cua-driver.

cua-driver lives under libs/cua-driver in the repository. The hosted docs describe the public interface; contributor details live next to the code so they stay close to implementation changes.

Source Map#

Path	Purpose
`libs/cua-driver/rust`	Rust workspace for the daemon, platform crates, testkit, and helper crates
`libs/cua-driver/typescript`	Rust-backed TypeScript SDK plus Node and Electron embedded-host adapters
`libs/cua-driver/python`	Python package wrapper around the driver binary
`libs/cua-driver/tests/fixtures`	Source-built GUI harness apps and shared fixtures
`libs/cua-driver/rust/crates/cua-driver/tests`	Rust integration tests for the driver and GUI harnesses
`libs/cua-driver/scripts`	Install, uninstall, local build, and VM sync helpers

Contributor Entry Points#

libs/cua-driver/README.md gives the repo-local overview.
libs/cua-driver/rust/README.md maps the Cargo workspace and test classes.
libs/cua-driver/rust/crates/cua-driver/tests/README.md explains Rust test naming and ignored GUI lanes.
libs/cua-driver/tests/fixtures/README.md explains source-built harness apps and staged outputs.
libs/cua-driver/scripts/README.md explains install and VM sync helpers.

Desktop Validation Entry Points#

The canonical GUI runners execute the complete Rust harness catalog. Their internal CI lanes may split shared, native, and capture owners for reporting, but contributors do not select those partitions directly.

Linux X11/session: scripts/ci/linux/run-rust-e2e.sh
Linux Sway:        scripts/ci/linux/run-rust-e2e-wayland.sh
Linux nested:      scripts/ci/linux/run-rust-e2e-inject.sh
Linux GNOME/KDE:   scripts/ci/linux/run-rust-e2e-desktop.sh <gnome|kde>
Linux real Xorg:   scripts/ci/linux/run-rust-e2e-desktop.sh xorg
Windows:           .\scripts\ci\windows\run-rust-e2e.ps1 -RequireGui
macOS:             scripts/ci/macos/run-rust-e2e.sh

The Sway runner creates a controlled stock-wlroots session. Nix owns the Linux source/package gate and provides the optional nested cua-compositor session; it is not the wrapper for every Linux E2E environment. GNOME, KDE, real Xorg, Windows, and macOS use an existing graphical login. Windows needs an interactive console or RDP session, and macOS needs a logged-in session with the required Accessibility and Screen Recording permissions. See Platform support for current capability boundaries, How Cua Driver is validated for the evidence model, and Platform roadmap for remaining work.

Build artifacts, VM logs, and local verification journals should stay out of git unless they have been promoted into a stable fixture or contributor doc.