xa11y 0.7.1

Cross-platform accessibility client library — unified API for reading and interacting with accessibility trees
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

# xa11y

[![Crates.io](https://img.shields.io/crates/v/xa11y)](https://crates.io/crates/xa11y)
[![PyPI](https://img.shields.io/pypi/v/xa11y)](https://pypi.org/project/xa11y/)
[![CI](https://github.com/xa11y/xa11y/actions/workflows/ci.yml/badge.svg)](https://github.com/xa11y/xa11y/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-xa11y.dev-blueviolet)](https://xa11y.dev)

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](https://xa11y.dev)** | **[Rust API](https://docs.rs/xa11y)** | **[Python API](https://xa11y.dev/api/python/)**

## Quick Example

```rust
use xa11y::*;

fn main() -> Result<()> {
    let safari = App::by_name("Safari")?;

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

    // Interact with elements via locator (re-resolves every call)
    safari.locator("button[name='Submit']").press()?;

    Ok(())
}
```

## Installation

```toml
[dependencies]
xa11y = "0.4"
```

> **macOS:** Grant your terminal **two** permissions in **System Settings > Privacy & Security**:
> 1. **Accessibility** — required for all accessibility API access.
> 2. **Screen & System Audio Recording** (macOS 26+) — required to read window content. Without this, only menu bars are visible.
>
> Restart your terminal after changing permissions.
>
> **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 |
| `show_menu` | Open a context menu |

## Platform Support

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

## Contributing

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

See the [development docs](https://xa11y.dev/guides/overview/) for architecture and setup.

## License

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