@crowecawcaw/xa11y

Cross-platform accessibility library for Node.js. One API for macOS, Windows, and Linux — built on top of the Rust xa11y crate, exposed via napi-rs.

Use cases: UI testing, AI agent tooling, desktop automation, accessibility auditing.

Documentation · JavaScript API · Rust API · Python API

Quick example

import { App } from '@crowecawcaw/xa11y';

const safari = await App.byName('Safari');

// Find elements with CSS-like selectors via locator
for (const button of await safari.locator('button').elements()) {
  console.log(button.name);
}

// Interact with elements (re-resolves on every call)
await safari.locator('button[name="Submit"]').press();
await safari.locator('text_field[name^="Search"]').setValue('hello world');

Installation

npm install @crowecawcaw/xa11y

Requires Node.js 18 or newer. Pre-built native binaries are published for Linux (x64/arm64), macOS (x64/arm64), and Windows (x64/arm64).

macOS: Grant your terminal (or the process running Node) two permissions in System Settings → Privacy & Security: Accessibility and Screen & System Audio Recording (macOS 26+). Accessibility lets xa11y read the AX tree. The second is required to read window content. Without it, only menu bars are visible. On macOS 27 and newer, the Accessibility grant lives in the Device Control and Data Access pane.

Async by default

Every operation that touches the accessibility tree is asynchronous and runs on a worker thread, so the Node event loop is never blocked. Property getters on Element snapshots are synchronous because the data is captured up front.

const app = await App.byName('com.example.MyApp');
const submit = await app.locator('button[name="Submit"]').element();

console.log(submit.role);   // sync — already captured
console.log(submit.enabled); // sync
await submit.children();    // async — re-queries the provider

Locators auto-wait

Action methods on Locator poll the tree until the element is visible and enabled, up to a 5-second budget, before performing the action. This makes tests resilient to UI populating asynchronously.

// Waits until the dialog appears AND its OK button is enabled, then clicks it.
await app.locator('dialog[name="Save Changes?"] button[name="OK"]').press();

Subscribing to events

Subscriptions extend Node's EventEmitter, so you can use the familiar .on() / .once() / .off() API. Events are emitted both under their specific type name and the catch-all 'event' name. Call close() (or pass an AbortSignal) to tear down the subscription.

const sub = await app.subscribe();
sub.on('focusChanged', (ev) => console.log('focus moved to', ev.target?.name));
sub.on('event', (ev) => console.log(ev.type, ev.appName));
// ... later
sub.close();

Waiting for a single event

Use waitForEvent() for Playwright-style one-shot waits with optional predicate and timeout:

const [opened] = await Promise.all([
  app.waitForEvent('windowOpened'),
  app.locator('button[name="Settings"]').press(),
]);

// With predicate + timeout
const ev = await sub.waitForEvent('focusChanged', {
  predicate: (e) => e.target?.role === 'button',
  timeout: 3000,
});

AbortSignal support

Both subscribe() and waitForEvent() accept an AbortSignal for cancellation:

const ctrl = new AbortController();
const sub = await app.subscribe({ signal: ctrl.signal });
sub.on('focusChanged', (ev) => { /* ... */ });
// ctrl.abort() closes the subscription automatically

Errors

All operations throw subclasses of XA11yError:

Catch a specific subclass and let the rest propagate:

import { App, SelectorNotMatchedError } from '@crowecawcaw/xa11y';

try {
  await app.locator('button[name="Submit"]').press();
} catch (err) {
  if (err instanceof SelectorNotMatchedError) {
    /* expected miss */
  } else {
    throw err;
  }
}

License

MIT — see LICENSE.