xa11y
cross-platform desktop automation via accessibility trees
Last verified:
What is xa11y?
xa11y is a Playwright-style API library for driving native desktop applications on macOS, Windows, and Linux through the accessibility tree. It provides a unified, cross-platform interface for reading and interacting with accessibility trees, enabling end-to-end UI testing, computer-use AI agents, and assistive technology tools. The library is written in Rust with Python and JavaScript bindings, offering a small, intuitive API that stays out of your way.
Key features include CSS-like flexible selectors for querying accessibility trees (e.g., button[name='Submit'], textfield[name^='Search'], group > button), the ability to synthesize mouse and keyboard events, capture screenshots of any element or region, and stream accessibility events in real time. The included CLI tool allows users to explore accessibility trees, find elements, debug tests, list running applications with PIDs, print full accessibility trees, and perform actions on matched elements. The library supports Locator patterns with wait methods like wait_visible(), wait_hidden(), wait_enabled(), wait_disabled(), wait_attached(), wait_detached(), wait_focused(), wait_unfocused(), and wait_until(predicate) for reliable async UI interactions.
xa11y is designed for software testers writing integration tests for desktop applications, AI developers building computer-use agents that control desktop apps, developers creating assistive technology tools, and anyone needing desktop automation across multiple platforms. It replaces the need for platform-specific accessibility APIs by providing one API that works on macOS (AXUIElement), Windows (UI Automation), and Linux (AT-SPI2), allowing users to write once and query anywhere.
xa11y pricing
Pricing model: Freemium
MIT-licensed open-source software available for free. No paid plans or tiers. Can be used freely in both commercial and open-source projects. Install via $ cargo add xa11y for Rust, $ pip install xa11y for Python, or $ npm install @crowecawcaw/xa11y for JavaScript.
xa11y pros
- Playwright-style API familiar to web testing developers
- Cross-platform support for macOS, Windows, and Linux
- One unified API across all three desktop platforms
- Written in Rust with Python and JavaScript bindings
- MIT-licensed with permissively licensed dependencies
- CSS-like flexible selector syntax for accessibility trees
- Includes CLI tool for exploring and debugging accessibility trees
- Can synthesize mouse and keyboard events
- Captures screenshots of any element or region
- Streams accessibility events in real time
- Locator pattern with automatic wait methods for async UIs
- Works with Electron and Chromium-based apps with launch flag
- No special permissions needed on Linux and Windows
- Pre-built wheels available for multiple platforms and architectures
- End-to-end example files shipped for each binding
- CI-tested integration examples that can't rot
- Selector groups (alternation) handle dynamic label changes
- Element.dump() and Element.tree() for structured snapshots
xa11y cons
- macOS requires two permissions: Accessibility and Screen & System Audio Recording
- Electron/Chromium apps need additional launch flag on Linux
- Requires Python 3.9+ for Python binding
- Requires Node.js 18+ for JavaScript binding
- Accessibility labels often differ from what's painted on screen
- Terminal must be restarted after permission changes on macOS
- CI machines are slower, requiring generous 5-10 second timeouts
- Only supports desktop platforms (no mobile or web)
Frequently asked questions about xa11y
What is xa11y and what does it do?
xa11y is a Playwright-style library for driving native desktop apps on macOS, Windows, and Linux via the accessibility tree. It provides a unified API for reading and interacting with accessibility trees, enabling end-to-end tests, computer-use agents, and assistive tools.
Which platforms does xa11y support?
xa11y supports macOS (using AXUIElement), Windows (using UI Automation), and Linux (using AT-SPI2). It provides one API that works across all three desktop platforms, allowing you to write once and query anywhere.
What language bindings are available?
xa11y is written in Rust and has Python and JavaScript bindings. Install with $ cargo add xa11y for Rust, $ pip install xa11y for Python (requires Python 3.9+), or $ npm install @crowecawcaw/xa11y for JavaScript (requires Node.js 18+).
How do I install xa11y?
Install via $ cargo add xa11y for Rust, $ pip install xa11y for Python, or $ npm install @crowecawcaw/xa11y for JavaScript. Pre-built wheels are available for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64).
What permissions are required on macOS?
macOS requires two permissions: 1) Accessibility (System Settings → Privacy & Security → Accessibility) and 2) Screen & System Audio Recording (macOS 26+, System Settings → Privacy & Security → Screen & System Audio Recording). Grant both to your terminal or IDE, then restart the terminal for changes to take effect.
What is the xa11y CLI used for?
The xa11y CLI is for exploring and debugging accessibility trees. Commands include xa11y apps (list running apps with PIDs), xa11y tree (print full accessibility tree), xa11y find (find elements matching CSS-like selectors), xa11y action (perform actions on matched elements), and xa11y events (stream accessibility events in real time).
How do I write selectors for xa11y?
Use CSS-like syntax: button for Button role elements, button[name='OK'] for exact name match, textfield[name^='Search'] for name starting with, textfield[name*='email'] for name containing, group > button for direct children, window button[name='OK'] for descendants, and button:nth(2) for the nth match. Comma separates alternation clauses.
What use cases does xa11y support?
Primary use cases include UI testing (end-to-end integration tests for desktop apps), AI agent tooling (computer-use agents that control desktop applications), assistive technology development, and general desktop automation across macOS, Windows, and Linux.
How does xa11y handle async UI updates?
xa11y provides wait methods that poll until a condition is met: wait_visible()/wait_hidden() for element appearance/disappearance, wait_enabled()/wait_disabled() for interactivity, wait_attached()/wait_detached() for tree existence, wait_focused()/wait_unfocused() for focus state, and wait_until(predicate) for arbitrary conditions. These are faster and more reliable than sleeping.
What is xa11y's licensing model?
xa11y is MIT-licensed with permissively licensed dependencies throughout. This means you can use it freely in both commercial and open-source projects without licensing restrictions or fees.