xa11y 0.3.0

Cross-platform accessibility client library — unified API for reading and interacting with accessibility trees
Documentation

xa11y

Crates.io PyPI CI License: MIT Docs

Cross-platform accessibility library for reading and interacting with accessibility trees. One API for macOS, Windows, and Linux.

Use cases: UI testing, AI agent tooling, assistive technology, desktop automation.

Documentation | Rust API | Python API

Quick Example

use xa11y::*;

fn main() -> Result<()> {
    // Get the accessibility tree for an app
    let root = app(&AppTarget::ByName("Safari".to_string()))?;

    // Find elements with CSS-like selectors
    let buttons = root.query("button[name='Submit']")?;
    println!("Found {} buttons", buttons.len());

    // Interact with elements
    let loc = locator(AppTarget::ByName("Safari".to_string()), "button[name='Submit']")?;
    loc.press()?;

    Ok(())
}

Installation

[dependencies]
xa11y = "0.2"

macOS: Grant accessibility permissions to your terminal in System Settings > Privacy & Security > Accessibility.

Linux: AT-SPI2 must be running (default on GNOME/most DEs). No special permissions needed.

Windows: No special permissions needed.

Selector Syntax

Query accessibility trees with CSS-like selectors:

Pattern Meaning
button Elements with role Button
button[name='OK'] Button named exactly "OK"
textfield[name^='Search'] Text field whose name starts with "Search"
textfield[name*='email'] Text field whose name contains "email"
group > button Buttons that are direct children of a group
window button Buttons anywhere inside a window
button:nth(2) The 2nd button match

Supported Actions

Action Description
press Click / activate
focus / blur Move or remove keyboard focus
toggle Toggle a checkbox or switch
expand / collapse Expand or collapse a disclosure
select Select an item
set_value Set a text field's value
type_text Type text into an element
increment / decrement Adjust a slider or stepper
scroll Scroll in a direction
show_menu Open a context menu

Platform Support

Platform Backend
macOS AXUIElement
Linux AT-SPI2 (D-Bus)
Windows UI Automation

Contributing

git clone https://github.com/xa11y/xa11y && cd xa11y
cargo build --workspace
cargo xtask check   # fmt, lint, test, python bindings

See the development docs for architecture and setup.

License

MIT. All dependencies are permissively licensed (MIT, Apache-2.0, BSD, or similar), enforced via cargo-deny.