TypeScript API

import { queuedScreenReader } from 'a11ied/test';

await using sr = await queuedScreenReader({ url: 'http://localhost:3000/checkout' });

sr.goTo({ role: 'button', name: 'Pay' });
sr.activate();
sr.expectSpoken(/order placed/iu);

Native sessions default to guarded. Commands check the observed foreground target, and typing checks between characters. Read the fresh current item, focus observations, and transcript after each action. If focus changes, refocus deliberately and inspect state before continuing. require-binding is an optional strict mode that refuses unavailable native binding. development bypasses target checks. Foreground checks do not guarantee that focus cannot change during dispatch.

await using stops the reader when the block ends, so no try and finally is needed. On a queued reader it also runs the commands still in the queue. The Vitest guide has a test file to copy and the browser mode configuration.

import {
  attachDocumentToDriverSession,
  resolveDocumentTarget,
  runDriverSessionAction,
  startDriverSession,
  stopDriverSession,
} from 'a11ied';

const url = 'http://localhost:3000/checkout';
const target = await resolveDocumentTarget({ url });

await startDriverSession({ target: 'virtual' });
await attachDocumentToDriverSession({ html: await target.readHtml(), url });

try {
  const result = await runDriverSessionAction({ action: 'next', payload: { kind: 'heading' } });

  console.log(result.state.lastSpokenPhrase);
  console.log(result.state.transcript);
} finally {
  await stopDriverSession();
}

startDriverSession's url option only records where the session came from. It does not fetch a page or open a browser for you.

For a virtual session, call attachDocumentToDriverSession with the markup, as shown above. For a real target, open the page yourself first, since VoiceOver and NVDA read whatever is already on screen. a1 sr start and screenReader from a11ied/test both do this work for you.

These are the functions the CLI runs. Calls use the active session by default. stopDriverSession can select a retained recovery owner with options.sessionId. A session started with mode: 'broker' lives in its own process until stopped or until idleTimeoutMinutes, which defaults to 30.

One in-process JSDOM reader can own the shared document at a time. A conflicting session fails with virtual-session-conflict before changing the document. Stop the owner, or use a separate process or browser engine. An ephemeral JSDOM action follows the same rule.

A test should use screenReader from a11ied/test instead: it owns the lifecycle and disposes the session with the test.

Every action result includes session.engine for a virtual session and state.transcript: an array of entries with an index, an ISO at timestamp, the phrase, the itemText when the reader reported one, and a checkpoint label on the entries checkpoint added.

runAxe runs axe-core (axe), an open-source rules engine that checks a page against a set of automated accessibility rules, and returns the raw result.

import { runAxe } from 'a11ied';

const result = await runAxe(
  { kind: 'goto', url: 'http://localhost:3000/checkout' },
  { wcagVersion: '2.2', level: 'AA' },
);

for (const violation of result.violations) {
  console.log(violation.id, violation.impact, violation.nodes[0]?.target);
}

The first argument is a DocumentLoad: { kind: 'goto', url } for a page Playwright navigates to, or { kind: 'html', html } for inline markup. resolveDocumentTarget builds one from a URL, a file path, - for stdin, or { html }, the same way the CLI resolves its positional target.

Scope the run with level, criterion, or ruleIds. The options type allows one of the three. Omit all three to run every rule mapped in the WCAG version.

The result has violations, passes, incomplete, inapplicable, the resolved ruleIds, and a selection object that says how the rule list was chosen.

withLoadedPage(load, callback, options?) keeps a browser page open during the callback. withInteractiveBrowserPage(url, callback, options?) uses a headed browser for interactive sign-in and navigation. Both accept the existing storage, cookies, headers, viewport, click, and wait options.

import { runAxe, withInteractiveBrowserPage } from 'a11ied';
import { screenReader } from 'a11ied/test';

await withInteractiveBrowserPage('https://createdbyfireside.com/', async (page) => {
   await using sr = await screenReader({ page });
   await sr.next('heading');
   return runAxe(
      { kind: 'goto', url: page.url() },
      { wcagVersion: '2.2', level: 'AA', page },
   );
});

Complete sign-in or open the interaction state inside the callback before collecting observations. Pass the same page to runAxe, buildAuditReport, and the core tree, title, and HTML readers. Screenshots use that page's Playwright API. These reads preserve the document, cookies, and session storage. A new scan always inspects the current UI.

An existing page rejects replacement setup and a different requested URL. Closed pages or main-document navigation during observation reject the result. Stopping the reader leaves the caller's page open. A second virtual reader on that page fails with virtual-session-conflict until the owner stops.

The page reader option supports the in-process virtual browser engine. Broker sessions and native readers cannot receive a Playwright page. This example verifies simulated behavior; it does not establish VoiceOver or NVDA evidence or complete WCAG coverage.

Browser virtual activation clicks the exact DOM element selected by the simulated reader. Playwright checks visibility and enabled state, scrolls the element into view, and moves the mouse before clicking. This can trigger hover behavior and differs from the JSDOM reader's simulated click. Activation waits for initiated navigation and never retries a detached target or an uncertain click. Same-document and hash changes preserve the reader state.

These functions read the Web Content Accessibility Guidelines (WCAG), the standard most accessibility requirements come from, one success criterion at a time. A success criterion is a numbered, testable requirement such as 4.1.3, assigned a conformance level of A, AA, or AAA.

import {
  listWcagCriteria,
  searchWcagCriteria,
  showWcagTestMethod,
  showWcagCriterion,
} from 'a11ied';

const status = showWcagCriterion('4.1.3', '2.2');

console.log(status.criterion.title, status.testMethod.method);

const { testMethod, strategy } = showWcagTestMethod('4.1.3', '2.2');

if (strategy.requiresRealTarget) {
  console.log('Needs a driver session:', strategy.procedureIds);
}

const levelAA = listWcagCriteria('AA', '2.2');
const matches = searchWcagCriteria('focus order', { version: '2.2', limit: 3 });

These functions read data bundled with the package, so they make no network request, except showWcagAxeRule, the one asynchronous lookup.

Relevant criteria

import { inspectRelevantCriteriaUrl, inspectCriterionUrl } from 'a11ied';

const matrix = await inspectRelevantCriteriaUrl('http://localhost:3000', '2.2');
const focusOrder = await inspectCriterionUrl('2.4.3', 'http://localhost:3000', '2.2');

console.log(focusOrder.assessment.state);
console.log(focusOrder.assessment.reasons);

Both fetch the URL and parse the returned HTML. Use inspectRelevantCriteriaTarget and inspectCriterionTarget when you already have a resolved document target rather than a URL.

import { createDoctorReport, renderDoctorText, resolveAvailableDefaultTarget } from 'a11ied';

const report = createDoctorReport();
const stepsLeft = report.actions.filter((action) => { return action.required; });

console.log(report.ready, stepsLeft);
console.log(renderDoctorText(report));

const { target, targetType, warning } = await resolveAvailableDefaultTarget();

resolveAvailableDefaultTarget checks whether the platform screen reader is ready for automation and falls back to virtual when it is not. The returned warning is set on every fallback.

Assessment lifecycle

A host agent uses these shared operations to coordinate a desktop WCAG assessment. The coordinator stores the work and validates proof. The agent performs the procedure, captures observations, and evaluates the result against the procedure's WCAG requirements.

These operations perform no target input themselves. Real reader evidence still requires a runtime receipt that verifies the target and session binding. Current native binding limitations remain unresolved; virtual or mocked checks cannot establish a complete native audit.

a11ied re-exports the public core helpers and is the package to depend on. Install a scoped package only when you need a lower-level API it does not re-export.