uiautomator

English | 简体中文

Rust async Android UI automation library with a Python uiautomator2-style API.

What This Crate Provides

• Device connection and mode routing (Auto, AtxAgent, Direct)
• Selector-based element lookup
• UiObject operations (click/input/clear/wait/info/text/bounds)
• Gestures, key events, screenshots, app lifecycle operations
• Structured errors with retry support for unstable device/RPC scenarios

Installation

Recommended first-use flow:

1. Run uiautomator-cli init once for each target device.
2. Use this crate in application code.

[dependencies]
uiautomator = "1.0.2"
tokio = { version = "1", features = ["full"] }

Optional ATX-Agent installer support:

[dependencies]
uiautomator = { version = "1.0.2", features = ["atx-agent-install"] }

Note:

• The uiautomator crate package does not embed multi-arch atx-agent binaries to keep publish size within crates.io limits.
• Recommended setup path is uiautomator-cli init (or equivalent external provisioning) before using AtxAgent mode.
• Device::connect(None) expects exactly one online ADB device. Pass Some("<serial>") when multiple devices are connected.

Minimal Example

use uiautomator::{Device, Selector};

#[tokio::main]
async fn main() -> uiautomator::Result<()> {
    let d = Device::connect(None).await?;

    let settings = d.find(Selector::new().text("Settings"));
    if settings.exists(None).await? {
        settings.click(None, None).await?;
    }

    Ok(())
}

Error Handling Example

use std::time::Duration;
use uiautomator::{Device, Error};

async fn run(device: &Device) -> Result<(), Error> {
    match device.app_wait("com.example.app", Some(Duration::from_secs(5))).await {
        Ok(pid) => {
            println!("app ready: {pid}");
            Ok(())
        }
        Err(Error::AppNotInstalled(pkg)) => Err(Error::AppNotInstalled(pkg)),
        Err(Error::AppCrashed(pkg)) => Err(Error::AppCrashed(pkg)),
        Err(Error::Timeout) => Err(Error::Timeout),
        Err(other) => Err(other),
    }
}

Modes

• Auto (default): try ATX-Agent first, fallback to Direct.
• AtxAgent: use ATX-Agent transport (recommended for long-running/stable automation).
• Direct: direct JSON-RPC transport (fast setup, lower robustness).

Common APIs

• Device: connect, info, find, click, swipe, press, screenshot, app_start, app_stop
• UiObject: exists, wait, wait_gone, click, long_click, set_text, clear_text, get_text, info
• Selector: text/resource-id/class/description plus regex and hierarchy (child/sibling)

Testing

cargo test

cargo test -- --ignored --nocapture --test-threads=1

For full device regression, use the repository script from root:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/device-full-test.ps1 -Serial <serial>

Documentation

• Public requirements/design/tasks/release docs:
  • ../docs/public/REQUIREMENTS.md
  • ../docs/public/DESIGN.md
  • ../docs/public/TASKS.md
  • ../docs/public/TESTING_RELEASE.md
• Error handling guide:
  • ERROR_HANDLING.md

Note: tests/** and examples/** stay in GitHub and are not included in the crates package by default.

License

MIT.