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
feat(cua-driver): add cua-driver test to check a new install end to end (CUA-3660) (#6765)
cua-agents[bot]afffae21a76a
diff --git a/docs/content/docs/cua-driver/reference/cli/index.mdx b/docs/content/docs/cua-driver/reference/cli/index.mdxindex 41dc1bdb0f..bd879f779a 100644--- a/docs/content/docs/cua-driver/reference/cli/index.mdx+++ b/docs/content/docs/cua-driver/reference/cli/index.mdx@@ -47,6 +47,7 @@ Serve MCP and call tools from the shell; run the daemon; grant permissions and d| <span id="cua-driver-permissions-grant"></span>[`cua-driver permissions grant`](/cua-driver/reference/cli/serve-and-configure#cua-driver-permissions-grant) | Launch CuaDriver through LaunchServices so the permission prompts are attributed to the app. || <span id="cua-driver-doctor"></span>[`cua-driver doctor`](/cua-driver/reference/cli/serve-and-configure#cua-driver-doctor) | Run platform-aware diagnostic probes. || <span id="cua-driver-diagnose"></span>[`cua-driver diagnose`](/cua-driver/reference/cli/serve-and-configure#cua-driver-diagnose) | Print a pasteable install-layout and permission-attribution report. |+| <span id="cua-driver-test"></span>[`cua-driver test`](/cua-driver/reference/cli/serve-and-configure#cua-driver-test) | Check that Cua Driver works on this computer. || <span id="cua-driver-config"></span>[`cua-driver config`](/cua-driver/reference/cli/serve-and-configure#cua-driver-config) | Read or mutate persistent driver configuration. || <span id="cua-driver-config-show"></span>[`cua-driver config show`](/cua-driver/reference/cli/serve-and-configure#cua-driver-config-show) | Print the full config. || <span id="cua-driver-config-get"></span>[`cua-driver config get`](/cua-driver/reference/cli/serve-and-configure#cua-driver-config-get) | Print one config key. |diff --git a/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx b/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdxindex 58ffbab241..56ede25009 100644--- a/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx+++ b/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx@@ -35,6 +35,7 @@ description: "Serve MCP and call tools from the shell; run the daemon; grant per| [`cua-driver permissions grant`](#cua-driver-permissions-grant) | Launch CuaDriver through LaunchServices so the permission prompts are attributed to the app. || [`cua-driver doctor`](#cua-driver-doctor) | Run platform-aware diagnostic probes. || [`cua-driver diagnose`](#cua-driver-diagnose) | Print a pasteable install-layout and permission-attribution report. |+| [`cua-driver test`](#cua-driver-test) | Check that Cua Driver works on this computer. || [`cua-driver config`](#cua-driver-config) | Read or mutate persistent driver configuration. || [`cua-driver config show`](#cua-driver-config-show) | Print the full config. || [`cua-driver config get`](#cua-driver-config-get) | Print one config key. |@@ -575,6 +576,30 @@ cua-driver diagnosecua-driver diagnose```+## `cua-driver test`++Check that Cua Driver works on this computer.++Checks permissions, a screen read, Cua Driver's own pointer, and (macOS) typing in a background TextEdit window that is closed without saving. Exit code is 0 when everything works and 1 when something needs fixing.++```text output+cua-driver test [OPTIONS]+```++| Flag | Type | Default | Description |+| --- | --- | --- | --- |+| <span id="cua-driver-test--json"></span>`--json` | boolean | `false` | Emit the result as JSON. |++**Examples**++```bash test="cli-shape" id="ref-cua-driver-test"+# Check that Cua Driver works on this computer+cua-driver test++# Emit the result as JSON+cua-driver test --json+```+## `cua-driver config`Read or mutate persistent driver configuration.diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rsindex f74e92ff35..c1536418a5 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs@@ -142,6 +142,10 @@ pub enum Command {fix: bool,},Diagnose,+ /// `cua-driver test [--json]` - check a new install end to end.+ Test {+ json: bool,+ },/// `cua-driver permissions status|grant [--json]` — report TCC status/// (with source attribution + a live capture probe) or raise the/// correctly-attributed grant by launching CuaDriver via LaunchServices.@@ -357,6 +361,7 @@ fn finite_command_name_from_args(args: &[String]) -> Option<&'static str> {Some("channel") => Some("channel"),Some("doctor") => Some("doctor"),Some("diagnose") => Some("diagnose"),+ Some("test") => Some("test"),Some("permissions") => Some("permissions"),Some("autostart") => Some("autostart"),Some("skills") => Some("skills"),@@ -722,6 +727,10 @@ pub fn parse_command() -> Command {println!(" hardcoded launch argv like _CUA_DRIVER_ARGS = [\"mcp\"].");println!(" --pretty / -p Pretty-print the JSON.");println!();+ println!("test options:");+ println!(" cua-driver test [--json] Check permissions, screen read, pointer and typing.");+ println!(" Exit 0 when Cua Driver works, 1 when something needs fixing.");+ println!();println!("doctor options:");println!(" --json Emit the probe report as JSON for scripting.");println!();@@ -968,6 +977,9 @@ pub fn parse_command() -> Command {Command::Doctor { json, fix }}Some("diagnose") => Command::Diagnose,+ Some("test") => Command::Test {+ json: args.iter().any(|a| a == "--json"),+ },Some("permissions") => {let subcommand = pos.next().unwrap_or("status").to_string();let json = args.iter().any(|a| a == "--json");@@ -2102,6 +2114,11 @@ pub fn build_manifest() -> serde_json::Value {{ "name": "--json", "type": "flag", "description": "Machine-readable doctor report." },{ "name": "--fix", "type": "flag", "description": "macOS: make LaunchServices forget every other copy of CuaDriver.app (no files are deleted)." }] },+ { "name": "test",+ "description": "Check a new install end to end: permissions, screen read, pointer, and typing in TextEdit (macOS). Exit 0 when it all works.",+ "args": [+ { "name": "--json", "type": "flag", "description": "Machine-readable result." }+ ] },{ "name": "diagnose","description": "Emit a developer-focused diagnostic dump suitable for bug reports.","args": [] },@@ -3764,7 +3781,7 @@ pub fn run_permissions_host_request_if_requested() -> Option<i32> {}#[cfg(target_os = "macos")]-fn request_permissions_via_launchservices(+pub(crate) fn request_permissions_via_launchservices(probe_direct_capture: bool,) -> Result<serde_json::Value, String> {use std::fs::OpenOptions;@@ -4185,6 +4202,7 @@ const HELP_SUBCOMMANDS: &[&str] = &["sessions","history","mcp-config",+ "test",];fn cli_docs_json() -> serde_json::Value {@@ -4657,6 +4675,15 @@ fn cli_docs_literal() -> serde_json::Value {"flags": [{"name":"json","short_name":null,"help":"Emit the probe report as JSON.","default_value":false},{"name":"fix","short_name":null,"help":"macOS: make LaunchServices forget every other copy of CuaDriver.app. No files are deleted.","default_value":false}],"subcommands": no_subcommands},+ {+ "name": "test",+ "abstract": "Check that Cua Driver works on this computer.",+ "discussion": "Checks permissions, a screen read, Cua Driver's own pointer, and (macOS) typing in a background TextEdit window that is closed without saving. Exit code is 0 when everything works and 1 when something needs fixing.",+ "arguments": no_args,+ "options": no_options,+ "flags": [{"name":"json","short_name":null,"help":"Emit the result as JSON.","default_value":false}],+ "subcommands": no_subcommands+ },{"name": "diagnose","abstract": "Print a pasteable install-layout and permission-attribution report.",@@ -4859,6 +4886,10 @@ const CLI_EXAMPLES: &[(&str, &[(&str, &str)])] = &[("cua-driver doctor --json", "Emit the probe report as JSON"),("cua-driver doctor --fix", "macOS: make macOS forget extra copies of the app (deletes no files)"),]),+ ("test", &[+ ("cua-driver test", "Check that Cua Driver works on this computer"),+ ("cua-driver test --json", "Emit the result as JSON"),+ ]),("diagnose", &[("cua-driver diagnose", "Print an install and permission report to paste into an issue")]),("autostart", &[("cua-driver autostart status", "Check the autostart entry")]),("autostart enable", &[("cua-driver autostart enable", "Start the daemon at every logon")]),diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rsindex 4bcdc4be6e..e2ac8e00a7 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs@@ -41,6 +41,7 @@ mod release_channel;mod release_source;mod responsibility;mod sdk_adapter;+mod selftest;mod serve;mod skills;mod stop;@@ -846,6 +847,9 @@ fn main() {cli::Command::Diagnose => {cli::run_diagnose_cmd();}+ cli::Command::Test { json } => {+ std::process::exit(selftest::run_cmd(json));+ }cli::Command::Permissions { subcommand, json } => {cli::run_permissions_cmd(&subcommand, json);}@@ -1156,6 +1160,9 @@ fn main() -> anyhow::Result<()> {cli::run_diagnose_cmd();Ok(())}+ cli::Command::Test { json } => {+ std::process::exit(selftest::run_cmd(json));+ }cli::Command::Permissions { subcommand, json } => {cli::run_permissions_cmd(&subcommand, json);Ok(())diff --git a/libs/cua-driver/rust/crates/cua-driver/src/selftest.rs b/libs/cua-driver/rust/crates/cua-driver/src/selftest.rsnew file mode 100644index 0000000000..4a38f7059a--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver/src/selftest.rs@@ -0,0 +1,934 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 Cua AI, Inc.++//! `cua-driver test` - prove a fresh install works, end to end.+//!+//! Each step runs through the running Cua Driver the same way `cua-driver+//! call` does, using existing tools only. The steps talk to a [`Backend`], so+//! the runner and the output can be tested with a fake.+//!+//! Exit codes: 0 everything works, 1 something needs fixing, 64 usage error.++use serde_json::{json, Value};++const PHRASE: &str = "Hello from Cua Driver";+const EXAMPLE_PROMPT: &str = "Use Cua Driver to open Calculator and work out 17 times 23.";++/// What the steps need from the machine. The real one talks to the daemon.+pub trait Backend {+ /// True when this machine can run the Mac text-editor check.+ fn runs_text_editor_check(&self) -> bool;+ /// True when the app (or a running daemon) is there to talk to.+ fn app_installed(&self) -> bool;+ fn daemon_running(&self) -> bool;+ fn start_daemon(&mut self) -> Result<(), String>;+ /// `structuredContent` of the permission check. Never prompts.+ fn permissions(&mut self) -> Result<Value, String>;+ /// Run one tool. Returns the whole result (`content`, `structuredContent`).+ /// `Err` when the tool refuses or fails.+ fn call(&mut self, tool: &str, args: Value) -> Result<Value, String>;+ fn sleep_ms(&mut self, ms: u64);+ /// Label shared by every call of this run.+ fn session(&self) -> String;+ /// An empty text file to type into, so the user's own documents stay untouched.+ fn make_scratch_file(&mut self) -> Result<String, String>;+ fn remove_scratch_file(&mut self, path: &str);+}++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum Outcome {+ Pass,+ Fail,+}++#[derive(Debug, Clone)]+pub struct Step {+ pub id: &'static str,+ pub outcome: Outcome,+ pub message: String,+ pub fix: Option<String>,+}++#[derive(Debug, Clone)]+pub struct Report {+ pub steps: Vec<Step>,+ /// A line explaining checks that do not run on this system.+ pub note: Option<String>,+}++impl Report {+ pub fn ok(&self) -> bool {+ self.steps.iter().all(|s| s.outcome != Outcome::Fail)+ }++ pub fn exit_code(&self) -> i32 {+ if self.ok() {+ 0+ } else {+ 1+ }+ }++ pub fn fixes(&self) -> Vec<&str> {+ self.steps+ .iter()+ .filter(|s| s.outcome == Outcome::Fail)+ .filter_map(|s| s.fix.as_deref())+ .collect()+ }++ pub fn to_text(&self) -> String {+ let mut out = String::new();+ for step in &self.steps {+ let mark = match step.outcome {+ Outcome::Pass => "\u{2713}",+ Outcome::Fail => "\u{2717}",+ };+ out.push_str(&format!("{mark} {}\n", step.message));+ }+ if let Some(note) = &self.note {+ out.push_str(&format!("{note}\n"));+ }+ if self.ok() {+ out.push_str(&format!(+ "Cua Driver works. Ask your agent: \"{EXAMPLE_PROMPT}\"\n"+ ));+ } else {+ out.push_str("\nWhat to fix:\n");+ for (i, fix) in self.fixes().iter().enumerate() {+ out.push_str(&format!("{}. {fix}\n", i + 1));+ }+ }+ out+ }++ pub fn to_json(&self) -> Value {+ let steps: Vec<Value> = self+ .steps+ .iter()+ .map(|s| {+ json!({+ "id": s.id,+ "status": match s.outcome {+ Outcome::Pass => "pass",+ Outcome::Fail => "fail",+ },+ "message": s.message,+ "fix": s.fix,+ })+ })+ .collect();+ json!({+ "ok": self.ok(),+ "steps": steps,+ "fixes": self.fixes(),+ "note": self.note,+ "example_prompt": if self.ok() { json!(EXAMPLE_PROMPT) } else { Value::Null },+ })+ }+}++fn pass(id: &'static str, message: &str) -> Step {+ Step {+ id,+ outcome: Outcome::Pass,+ message: message.to_owned(),+ fix: None,+ }+}++fn fail(id: &'static str, message: &str, fix: &str) -> Step {+ Step {+ id,+ outcome: Outcome::Fail,+ message: message.to_owned(),+ fix: Some(fix.to_owned()),+ }+}++fn flag(value: &Value, key: &str) -> bool {+ value.get(key).and_then(Value::as_bool).unwrap_or(false)+}++fn structured(result: &Value) -> &Value {+ result.get("structuredContent").unwrap_or(result)+}++/// Run every step and stop at the first one that fails.+pub fn run(backend: &mut dyn Backend) -> Report {+ let mut steps: Vec<Step> = Vec::new();+ let mut note = None;++ let grant = "run `cua-driver permissions grant`";++ // 1. Make sure Cua Driver is up, then ask what it may do.+ if !backend.daemon_running() {+ if !backend.app_installed() {+ steps.push(fail(+ "permissions",+ "Cua Driver is not installed",+ "Install Cua Driver: /bin/bash -c \"$(curl -fsSL https://cua.ai/driver/install.sh)\"",+ ));+ return Report { steps, note };+ }+ if let Err(error) = backend.start_daemon() {+ steps.push(fail(+ "permissions",+ &format!("Cua Driver would not start ({error})"),+ &format!("Start Cua Driver and turn on its access: {grant}"),+ ));+ return Report { steps, note };+ }+ }+ let perms = backend.permissions();+ let (ax, sr) = match &perms {+ Ok(p) => (flag(p, "accessibility"), flag(p, "screen_recording")),+ Err(_) => (false, false),+ };+ steps.push(if ax {+ pass(+ "accessibility",+ "Cua Driver can use your mouse and keyboard",+ )+ } else {+ fail(+ "accessibility",+ "Cua Driver can't use your mouse and keyboard yet",+ &format!("Turn on Accessibility for Cua Driver: {grant}"),+ )+ });+ steps.push(if sr {+ pass("screen_recording", "Cua Driver can see your screen")+ } else {+ fail(+ "screen_recording",+ "Cua Driver can't see your screen yet",+ &format!("Turn on Screen Recording for Cua Driver: {grant}"),+ )+ });+ if !(ax && sr) {+ return Report { steps, note };+ }++ // 2. Read the screen.+ let screen = backend.call(+ "get_desktop_state",+ json!({ "max_image_dimension": 640, "session": backend.session() }),+ );+ match screen {+ Ok(result) if has_image(&result) => {+ steps.push(pass("screen_read", "Cua Driver read your screen"))+ }+ Ok(_) => {+ steps.push(fail(+ "screen_read",+ "Cua Driver got a blank picture of your screen",+ &format!("Check Screen Recording is on for Cua Driver, then run `cua-driver test` again: {grant}"),+ ));+ return Report { steps, note };+ }+ Err(error) => {+ steps.push(fail(+ "screen_read",+ &format!("Cua Driver couldn't read your screen ({})", short(&error)),+ &format!("Check Screen Recording is on for Cua Driver: {grant}"),+ ));+ return Report { steps, note };+ }+ }++ // 3. Move Cua Driver's own pointer (never the real mouse).+ match backend.call(+ "move_cursor",+ json!({ "x": 320, "y": 240, "session": backend.session() }),+ ) {+ Ok(_) => steps.push(pass("pointer", "Cua Driver moved its own pointer")),+ Err(error) => {+ steps.push(fail(+ "pointer",+ &format!("Cua Driver couldn't move its pointer ({})", short(&error)),+ "Run `cua-driver doctor` and send us what it prints.",+ ));+ return Report { steps, note };+ }+ }++ // 4. Type into a document and read it back.+ if backend.runs_text_editor_check() {+ let step = text_editor_check(backend);+ let failed = step.outcome == Outcome::Fail;+ steps.push(step);+ if failed {+ let _ = backend.call("end_session", json!({ "session": backend.session() }));+ return Report { steps, note };+ }+ } else {+ note = Some("Typing in a document is only checked on a Mac for now.".to_owned());+ }+ let _ = backend.call("end_session", json!({ "session": backend.session() }));+ Report { steps, note }+}++fn short(error: &str) -> String {+ let first = error.lines().next().unwrap_or(error).trim();+ if first.chars().count() > 120 {+ let cut: String = first.chars().take(117).collect();+ format!("{cut}...")+ } else {+ first.to_owned()+ }+}++fn has_image(result: &Value) -> bool {+ result+ .get("content")+ .and_then(Value::as_array)+ .map(|items| {+ items.iter().any(|item| {+ item.get("type").and_then(Value::as_str) == Some("image")+ && item+ .get("data")+ .and_then(Value::as_str)+ .is_some_and(|d| d.len() > 200)+ })+ })+ .unwrap_or(false)+}++fn text_editor_check(backend: &mut dyn Backend) -> Step {+ let id = "text_editor";+ let doctor = "Run `cua-driver doctor` and send us what it prints.";+ // A fresh TextEdit instance on a scratch file, so the user's own TextEdit+ // windows and documents are never touched.+ let scratch = match backend.make_scratch_file() {+ Ok(path) => path,+ Err(error) => {+ return fail(+ id,+ &format!(+ "Cua Driver couldn't prepare a test file ({})",+ short(&error)+ ),+ doctor,+ )+ }+ };+ let step = text_editor_run(backend, &scratch);+ backend.remove_scratch_file(&scratch);+ step+}++fn text_editor_run(backend: &mut dyn Backend, scratch: &str) -> Step {+ let id = "text_editor";+ let doctor = "Run `cua-driver doctor` and send us what it prints.";+ let launched = match backend.call(+ "launch_app",+ json!({ "bundle_id": "com.apple.TextEdit", "creates_new_application_instance": true,+ "urls": [scratch], "session": backend.session() }),+ ) {+ Ok(v) => v,+ Err(error) => {+ return fail(+ id,+ &format!("Cua Driver couldn't open TextEdit ({})", short(&error)),+ doctor,+ )+ }+ };+ let pid = structured(&launched).get("pid").and_then(Value::as_i64);+ let Some(pid) = pid else {+ return fail(id, "Cua Driver couldn't open TextEdit", doctor);+ };++ let result = type_and_read_back(backend, pid);+ // Always tidy up, whatever happened above.+ let closed = close_without_saving(backend, pid);+ // Quit the TextEdit this test started (best effort; only works for our own launch).+ let _ = backend.call(+ "kill_app",+ json!({ "pid": pid, "session": backend.session() }),+ );+ match (result, closed) {+ (Ok(()), Ok(())) => pass(id, "Cua Driver typed in TextEdit and read it back"),+ (Ok(()), Err(_)) => fail(+ id,+ "Cua Driver typed in TextEdit, but couldn't close the test document",+ "Close the empty TextEdit window that is left over and choose Delete.",+ ),+ (Err(error), _) => fail(+ id,+ &format!("Cua Driver couldn't type in TextEdit ({})", short(&error)),+ doctor,+ ),+ }+}++fn visible_window(backend: &mut dyn Backend, pid: i64) -> Result<Option<i64>, String> {+ let listed = backend.call(+ "list_windows",+ json!({ "pid": pid, "session": backend.session() }),+ )?;+ let windows = structured(&listed)+ .get("windows")+ .and_then(Value::as_array)+ .cloned()+ .unwrap_or_default();+ Ok(windows+ .iter()+ .filter(|w| w.get("layer").and_then(Value::as_i64).unwrap_or(0) == 0)+ .filter(|w| {+ w.get("is_on_screen")+ .and_then(Value::as_bool)+ .unwrap_or(true)+ })+ .find_map(|w| w.get("window_id").and_then(Value::as_i64)))+}++fn find_window(backend: &mut dyn Backend, pid: i64) -> Result<i64, String> {+ for _ in 0..20 {+ if let Some(id) = visible_window(backend, pid)? {+ return Ok(id);+ }+ backend.sleep_ms(400);+ }+ Err("TextEdit showed no window".to_owned())+}++fn read_elements(+ backend: &mut dyn Backend,+ pid: i64,+ window_id: i64,+) -> Result<Vec<Value>, String> {+ let read = backend.call(+ "get_window_state",+ json!({ "pid": pid, "window_id": window_id, "include_screenshot": false,+ "full_output": true, "timeout_ms": 5000, "session": backend.session() }),+ )?;+ Ok(structured(&read)+ .get("elements")+ .and_then(Value::as_array)+ .cloned()+ .unwrap_or_default())+}++fn token(element: &Value) -> Option<String> {+ element+ .get("element_token")+ .and_then(Value::as_str)+ .map(str::to_owned)+}++fn type_and_read_back(backend: &mut dyn Backend, pid: i64) -> Result<(), String> {+ let window_id = find_window(backend, pid)?;+ let elements = read_elements(backend, pid, window_id)?;+ let area = elements+ .iter()+ .find(|e| e.get("role").and_then(Value::as_str) == Some("AXTextArea"))+ .and_then(token)+ .ok_or("no text area in the TextEdit window")?;+ backend.call(+ "type_text",+ json!({ "pid": pid, "window_id": window_id, "element_token": area, "text": PHRASE, "session": backend.session() }),+ )?;+ let read = backend.call(+ "get_window_state",+ json!({ "pid": pid, "window_id": window_id, "include_screenshot": false,+ "query": "Hello", "timeout_ms": 5000, "session": backend.session() }),+ )?;+ let tree = structured(&read)+ .get("tree_markdown")+ .and_then(Value::as_str)+ .unwrap_or("");+ if tree.contains(PHRASE) {+ Ok(())+ } else {+ Err("the typed text was not in the window".to_owned())+ }+}++/// Press the window's close button, then choose Delete on the save sheet.+fn close_without_saving(backend: &mut dyn Backend, pid: i64) -> Result<(), String> {+ let window_id = match visible_window(backend, pid)? {+ Some(id) => id,+ None => return Ok(()), // nothing left to close+ };+ let elements = read_elements(backend, pid, window_id)?;+ // The close button is the left-most unlabeled button on the window's title bar.+ let close = elements+ .iter()+ .filter(|e| {+ e.get("role").and_then(Value::as_str) == Some("AXButton")+ && e.get("parent_index").and_then(Value::as_i64) == Some(0)+ })+ .min_by(|a, b| {+ let x = |e: &Value| e["frame"]["x"].as_f64().unwrap_or(f64::MAX);+ x(a).total_cmp(&x(b))+ })+ .and_then(token)+ .ok_or("no close button")?;+ backend.call(+ "click",+ json!({ "pid": pid, "window_id": window_id, "element_token": close, "session": backend.session() }),+ )?;+ // A saved file closes at once. If a save sheet shows up, choose Delete.+ for _ in 0..10 {+ backend.sleep_ms(300);+ if visible_window(backend, pid)?.is_none() {+ return Ok(());+ }+ let elements = read_elements(backend, pid, window_id)?;+ let sheet_delete = elements.iter().find(|e| {+ e.get("role").and_then(Value::as_str) == Some("AXButton")+ && e.get("label").and_then(Value::as_str) == Some("Delete")+ });+ if let Some(button) = sheet_delete.and_then(token) {+ backend.call(+ "click",+ json!({ "pid": pid, "window_id": window_id, "element_token": button, "session": backend.session() }),+ )?;+ }+ }+ Err("the window did not close".to_owned())+}++/// The real thing: talks to the installed Cua Driver.+pub struct DaemonBackend {+ socket: String,+}++impl DaemonBackend {+ pub fn new() -> Self {+ Self {+ socket: crate::serve::default_socket_path(),+ }+ }+}++impl Backend for DaemonBackend {+ fn runs_text_editor_check(&self) -> bool {+ cfg!(target_os = "macos")+ }++ fn app_installed(&self) -> bool {+ #[cfg(target_os = "macos")]+ {+ std::path::Path::new(&crate::bundle::app_bundle_path()).exists()+ }+ #[cfg(not(target_os = "macos"))]+ {+ true+ }+ }++ fn daemon_running(&self) -> bool {+ crate::serve::is_daemon_listening(&self.socket)+ }++ fn start_daemon(&mut self) -> Result<(), String> {+ // Same launch `permissions grant` and `mcp` use: on a Mac this opens the+ // installed app through LaunchServices, so access is tied to Cua Driver.+ crate::cli::launch_daemon_and_wait(+ &self.socket,+ 30,+ false,+ &[],+ crate::history_runtime::preview_admitted_preference(),+ )+ .map_err(|e| e.to_string())+ }++ fn permissions(&mut self) -> Result<Value, String> {+ let request = crate::serve::DaemonRequest {+ method: "call".into(),+ name: Some("check_permissions".into()),+ args: Some(json!({ "prompt": false, "probe_direct_capture": false })),+ session_id: None,+ observation_origin: Some(crate::serve::ToolObservationOrigin::Direct),+ client_kind: Some(cua_driver_core::daemon::DaemonClientKind::Cli),+ };+ let answered = crate::serve::send_request(&self.socket, &request)+ .ok()+ .filter(|r| r.ok)+ .and_then(|r| r.result)+ .and_then(|r| r.get("structuredContent").cloned());+ if let Some(status) = answered {+ return Ok(status);+ }+ #[cfg(target_os = "macos")]+ {+ // The app may still be inside its first-launch permission step.+ return crate::cli::request_permissions_via_launchservices(false);+ }+ #[cfg(not(target_os = "macos"))]+ Err("no answer".to_owned())+ }++ fn call(&mut self, tool: &str, args: Value) -> Result<Value, String> {+ let mut args = args;+ cua_driver_core::tool_args::sanitize_reserved_args(&mut args);+ let request = crate::serve::DaemonRequest {+ method: "call".into(),+ name: Some(tool.to_owned()),+ args: Some(args),+ session_id: Some("cli-explicit".to_owned()),+ observation_origin: Some(crate::serve::ToolObservationOrigin::Direct),+ client_kind: Some(cua_driver_core::daemon::DaemonClientKind::Cli),+ };+ let response =+ crate::serve::send_request(&self.socket, &request).map_err(|e| e.to_string())?;+ if !response.ok {+ return Err(response+ .error+ .unwrap_or_else(|| "the call failed".to_owned()));+ }+ let result = response.result.unwrap_or(Value::Null);+ let refused = result+ .get("isError")+ .and_then(Value::as_bool)+ .unwrap_or(false)+ || structured(&result).get("status").and_then(Value::as_str) == Some("refused");+ if refused {+ let reason = structured(&result)+ .get("refusal")+ .and_then(|r| r.get("message"))+ .and_then(Value::as_str)+ .or_else(|| result["content"][0]["text"].as_str())+ .unwrap_or("the tool refused");+ return Err(reason.to_owned());+ }+ Ok(result)+ }++ fn sleep_ms(&mut self, ms: u64) {+ std::thread::sleep(std::time::Duration::from_millis(ms));+ }++ fn session(&self) -> String {+ format!("cua-driver-test-{}", std::process::id())+ }++ fn make_scratch_file(&mut self) -> Result<String, String> {+ let path = std::env::temp_dir().join(format!("cua-driver-test-{}.txt", std::process::id()));+ std::fs::write(&path, "").map_err(|e| e.to_string())?;+ Ok(path.to_string_lossy().into_owned())+ }++ fn remove_scratch_file(&mut self, path: &str) {+ let _ = std::fs::remove_file(path);+ }+}++/// Entry point for `cua-driver test [--json]`. Returns the exit code.+pub fn run_cmd(json_output: bool) -> i32 {+ let mut backend = DaemonBackend::new();+ let report = run(&mut backend);+ if json_output {+ println!(+ "{}",+ serde_json::to_string_pretty(&report.to_json()).unwrap_or_default()+ );+ } else {+ print!("{}", report.to_text());+ }+ report.exit_code()+}++#[cfg(test)]+mod tests {+ use super::*;++ struct Fake {+ installed: bool,+ running: bool,+ start_ok: bool,+ perms: Value,+ text_editor: bool,+ calls: Vec<String>,+ closed: bool,+ started: bool,+ typed: bool,+ screen_blank: bool,+ scratch_removed: bool,+ }++ impl Fake {+ fn good() -> Self {+ Fake {+ installed: true,+ running: true,+ start_ok: true,+ perms: json!({ "accessibility": true, "screen_recording": true }),+ text_editor: true,+ calls: vec![],+ closed: false,+ started: false,+ typed: false,+ screen_blank: false,+ scratch_removed: false,+ }+ }+ }++ fn element(index: u32, role: &str, label: Option<&str>, parent: u32, x: f64) -> Value {+ json!({ "element_token": format!("s1:{index}"), "role": role, "label": label,+ "parent_index": parent, "frame": { "x": x, "y": 85.0, "w": 16.0, "h": 16.0 } })+ }++ impl Backend for Fake {+ fn runs_text_editor_check(&self) -> bool {+ self.text_editor+ }+ fn app_installed(&self) -> bool {+ self.installed+ }+ fn daemon_running(&self) -> bool {+ self.running+ }+ fn start_daemon(&mut self) -> Result<(), String> {+ self.started = true;+ if self.start_ok {+ self.running = true;+ Ok(())+ } else {+ Err("timed out".into())+ }+ }+ fn permissions(&mut self) -> Result<Value, String> {+ Ok(self.perms.clone())+ }+ fn call(&mut self, tool: &str, args: Value) -> Result<Value, String> {+ self.calls.push(tool.to_owned());+ match tool {+ "get_desktop_state" => {+ let data = if self.screen_blank {+ ""+ } else {+ &"x".repeat(500)+ };+ Ok(json!({ "content": [{ "type": "image", "data": data }] }))+ }+ "move_cursor" => Ok(json!({ "structuredContent": {} })),+ "launch_app" => Ok(json!({ "structuredContent": { "pid": 42 } })),+ "list_windows" => {+ let windows = if self.closed {+ json!([])+ } else {+ json!([{ "window_id": 7, "layer": 0 }])+ };+ Ok(json!({ "structuredContent": { "windows": windows } }))+ }+ "get_window_state" => {+ if args.get("query").is_some() {+ let tree = if self.typed {+ format!("AXTextArea = \"{PHRASE}\"")+ } else {+ String::new()+ };+ return Ok(json!({ "structuredContent": { "tree_markdown": tree } }));+ }+ let elements = vec![+ element(1, "AXTextArea", None, 0, 300.0),+ element(34, "AXButton", None, 0, 221.0),+ element(36, "AXButton", None, 0, 244.0),+ ];+ Ok(json!({ "structuredContent": { "elements": elements } }))+ }+ "type_text" => {+ self.typed = args["text"] == PHRASE && args["element_token"] == "s1:1";+ Ok(json!({ "structuredContent": { "effect": "confirmed" } }))+ }+ "click" => {+ match args["element_token"].as_str() {+ Some("s1:34") => self.closed = true,+ _ => panic!("clicked the wrong thing: {args}"),+ }+ Ok(json!({ "structuredContent": {} }))+ }+ _ => Ok(json!({})),+ }+ }+ fn sleep_ms(&mut self, _ms: u64) {}+ fn session(&self) -> String {+ "t".into()+ }+ fn make_scratch_file(&mut self) -> Result<String, String> {+ Ok("/tmp/scratch.txt".into())+ }+ fn remove_scratch_file(&mut self, _path: &str) {+ self.scratch_removed = true;+ }+ }++ #[test]+ fn everything_works() {+ let mut fake = Fake::good();+ let report = run(&mut fake);+ assert!(report.ok());+ assert_eq!(report.exit_code(), 0);+ let text = report.to_text();+ assert_eq!(text.lines().count(), 6, "{text}");+ assert!(text.contains("Cua Driver works. Ask your agent:"));+ assert!(!text.contains("What to fix"));+ assert!(fake.closed, "the test document is closed");+ assert!(fake.scratch_removed, "the scratch file is removed");+ assert!(fake.calls.contains(&"kill_app".to_owned()));+ assert_eq!(report.to_json()["ok"], true);+ assert_eq!(report.to_json()["steps"].as_array().unwrap().len(), 5);+ }++ #[test]+ fn missing_accessibility_stops_with_one_fix() {+ let mut fake = Fake::good();+ fake.perms = json!({ "accessibility": false, "screen_recording": true });+ let report = run(&mut fake);+ assert!(!report.ok());+ assert_eq!(report.exit_code(), 1);+ let text = report.to_text();+ assert!(text.contains("\u{2717} Cua Driver can't use your mouse and keyboard"));+ assert!(text.contains("\u{2713} Cua Driver can see your screen"));+ assert!(text.contains(+ "1. Turn on Accessibility for Cua Driver: run `cua-driver permissions grant`"+ ));+ assert!(!text.contains("Cua Driver works"));+ assert!(fake.calls.is_empty(), "no tool runs once access is missing");+ }++ #[test]+ fn missing_screen_recording_stops_with_one_fix() {+ let mut fake = Fake::good();+ fake.perms = json!({ "accessibility": true, "screen_recording": false });+ let report = run(&mut fake);+ assert_eq!(report.exit_code(), 1);+ let text = report.to_text();+ assert!(text.contains(+ "1. Turn on Screen Recording for Cua Driver: run `cua-driver permissions grant`"+ ));+ assert!(!text.contains("2."));+ assert_eq!(report.to_json()["fixes"].as_array().unwrap().len(), 1);+ }++ #[test]+ fn both_missing_lists_both_fixes_without_jargon() {+ let mut fake = Fake::good();+ fake.perms = json!({});+ let text = run(&mut fake).to_text();+ assert!(text.contains("1. Turn on Accessibility"));+ assert!(text.contains("2. Turn on Screen Recording"));+ for word in ["TCC", "daemon", " AX "] {+ assert!(!text.contains(word), "{word} in {text}");+ }+ }++ #[test]+ fn no_app_installed() {+ let mut fake = Fake::good();+ fake.running = false;+ fake.installed = false;+ let report = run(&mut fake);+ assert_eq!(report.exit_code(), 1);+ assert!(+ !fake.started,+ "does not try to start an app that is not there"+ );+ let text = report.to_text();+ assert!(text.contains("Cua Driver is not installed"));+ assert!(text.contains("cua.ai/driver/install.sh"));+ }++ #[test]+ fn starts_cua_driver_when_it_is_not_running() {+ let mut fake = Fake::good();+ fake.running = false;+ assert!(run(&mut fake).ok());+ assert!(fake.started);+ }++ #[test]+ fn a_start_that_fails_says_how_to_continue() {+ let mut fake = Fake::good();+ fake.running = false;+ fake.start_ok = false;+ let report = run(&mut fake);+ assert_eq!(report.exit_code(), 1);+ assert!(report.to_text().contains("cua-driver permissions grant"));+ }++ #[test]+ fn a_blank_screen_read_fails() {+ let mut fake = Fake::good();+ fake.screen_blank = true;+ let report = run(&mut fake);+ assert_eq!(report.exit_code(), 1);+ assert!(report.to_text().contains("blank picture"));+ assert!(!fake.calls.contains(&"move_cursor".to_owned()));+ }++ #[test]+ fn text_that_never_shows_up_fails_and_still_cleans_up() {+ struct NoText(Fake);+ impl Backend for NoText {+ fn runs_text_editor_check(&self) -> bool {+ true+ }+ fn app_installed(&self) -> bool {+ true+ }+ fn daemon_running(&self) -> bool {+ true+ }+ fn start_daemon(&mut self) -> Result<(), String> {+ Ok(())+ }+ fn permissions(&mut self) -> Result<Value, String> {+ self.0.permissions()+ }+ fn call(&mut self, tool: &str, args: Value) -> Result<Value, String> {+ if tool == "type_text" {+ return Err("refused".into());+ }+ self.0.call(tool, args)+ }+ fn sleep_ms(&mut self, _: u64) {}+ fn session(&self) -> String {+ "t".into()+ }+ fn make_scratch_file(&mut self) -> Result<String, String> {+ self.0.make_scratch_file()+ }+ fn remove_scratch_file(&mut self, p: &str) {+ self.0.remove_scratch_file(p)+ }+ }+ let mut backend = NoText(Fake::good());+ let report = run(&mut backend);+ assert_eq!(report.exit_code(), 1);+ assert!(report.to_text().contains("couldn't type in TextEdit"));+ assert!(+ backend.0.closed,+ "the document is closed even when typing failed"+ );+ }++ #[test]+ fn linux_skips_the_text_editor_and_says_so() {+ let mut fake = Fake::good();+ fake.text_editor = false;+ let report = run(&mut fake);+ assert!(report.ok());+ assert!(report.to_text().contains("only checked on a Mac"));+ assert!(!fake.calls.contains(&"launch_app".to_owned()));+ assert_eq!(report.to_json()["steps"].as_array().unwrap().len(), 4);+ }++ #[test]+ fn json_marks_failures_with_fixes() {+ let mut fake = Fake::good();+ fake.perms = json!({ "accessibility": false, "screen_recording": true });+ let json = run(&mut fake).to_json();+ assert_eq!(json["ok"], false);+ assert_eq!(json["steps"][0]["id"], "accessibility");+ assert_eq!(json["steps"][0]["status"], "fail");+ assert_eq!(json["steps"][1]["status"], "pass");+ assert!(json["fixes"][0].as_str().unwrap().contains("Accessibility"));+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/selftest_cli_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/selftest_cli_test.rsnew file mode 100644index 0000000000..abdb9d372f--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver/tests/selftest_cli_test.rs@@ -0,0 +1,45 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 Cua AI, Inc.++//! `cua-driver test` is registered in the CLI help and reference.++use std::process::Command;++fn run(args: &[&str]) -> String {+ let home = tempfile::tempdir().expect("temp home");+ let output = Command::new(env!("CARGO_BIN_EXE_cua-driver"))+ .args(args)+ .env("CUA_DRIVER_RS_HOME", home.path())+ .env("CUA_DRIVER_RS_TELEMETRY_ENABLED", "0")+ .output()+ .expect("run cua-driver");+ assert!(output.status.success(), "{args:?}: {:?}", output.status);+ String::from_utf8(output.stdout).expect("UTF-8 output")+}++#[test]+fn test_command_is_listed_in_help() {+ let help = run(&["--help"]);+ assert!(help.contains("test"), "{help}");+ assert!(help.contains("cua-driver test [--json]"), "{help}");+}++#[test]+fn test_command_has_its_own_reference_page() {+ let page = run(&["test", "--help"]);+ assert!(page.contains("--json"), "{page}");+ assert!(page.contains("Exit code is 0"), "{page}");+}++#[test]+fn test_command_is_in_the_manifest() {+ let manifest: serde_json::Value =+ serde_json::from_str(&run(&["manifest"])).expect("manifest JSON");+ let names: Vec<&str> = manifest["subcommands"]+ .as_array()+ .unwrap()+ .iter()+ .filter_map(|c| c["name"].as_str())+ .collect();+ assert!(names.contains(&"test"), "{names:?}");+}diff --git a/scripts/docs-generators/cli-specs/cua-driver.json b/scripts/docs-generators/cli-specs/cua-driver.jsonindex 62a6363d93..dc2f83040c 100644--- a/scripts/docs-generators/cli-specs/cua-driver.json+++ b/scripts/docs-generators/cli-specs/cua-driver.json@@ -1351,6 +1351,32 @@"options": [],"subcommands": []},+ {+ "abstract": "Check that Cua Driver works on this computer.",+ "arguments": [],+ "discussion": "Checks permissions, a screen read, Cua Driver's own pointer, and (macOS) typing in a background TextEdit window that is closed without saving. Exit code is 0 when everything works and 1 when something needs fixing.",+ "examples": [+ {+ "command": "cua-driver test",+ "description": "Check that Cua Driver works on this computer"+ },+ {+ "command": "cua-driver test --json",+ "description": "Emit the result as JSON"+ }+ ],+ "flags": [+ {+ "default_value": false,+ "help": "Emit the result as JSON.",+ "name": "json",+ "short_name": null+ }+ ],+ "name": "test",+ "options": [],+ "subcommands": []+ },{"abstract": "Print a pasteable install-layout and permission-attribution report.","arguments": [],diff --git a/scripts/docs-generators/cua-driver-platform.test.ts b/scripts/docs-generators/cua-driver-platform.test.tsindex cf33f9a5b7..ba4021279d 100644--- a/scripts/docs-generators/cua-driver-platform.test.ts+++ b/scripts/docs-generators/cua-driver-platform.test.ts@@ -18,7 +18,7 @@ import { stableJson } from './lib/mdx';const CLI_COMMANDS = ['mcp', 'mcp-config', 'list-tools', 'describe', 'call', 'manifest', 'dump-docs', 'serve', 'stop', 'status', 'sessions',- 'revoke', 'autostart', 'permissions', 'doctor', 'diagnose', 'recording', 'history', 'config', 'telemetry',+ 'revoke', 'autostart', 'permissions', 'doctor', 'diagnose', 'test', 'recording', 'history', 'config', 'telemetry','cursor-theme', 'cursor', 'skills', 'extension', 'perception', 'check-update', 'update', 'channel',];diff --git a/scripts/docs-generators/cua-driver.ts b/scripts/docs-generators/cua-driver.tsindex cdd4ee0121..5c5427e55f 100644--- a/scripts/docs-generators/cua-driver.ts+++ b/scripts/docs-generators/cua-driver.ts@@ -194,7 +194,7 @@ export const CLI_GROUPS: CliGroup[] = [commands: ['mcp', 'mcp-config', 'list-tools', 'describe', 'call', 'manifest', 'dump-docs','serve', 'stop', 'status', 'sessions', 'revoke', 'autostart',- 'permissions', 'doctor', 'diagnose',+ 'permissions', 'doctor', 'diagnose', 'test','config', 'telemetry', 'cursor-theme', 'cursor','check-update', 'update', 'channel',],