Skip to content

Run an audit of your journeys

If you want to test what a real screen reader experiences on your app — not what a static scan can infer from source — run b8e audit. It drives your project’s journeys through a real browser paired with a real screen reader and reports what a user of assistive technology actually hits.

For a mobile project, the same command drives the platform’s own screen reader instead of a browser: TalkBack on an Android device or emulator, or VoiceOver on an iOS Simulator. See Run an Android audit with TalkBack for what the device needs, and Run an iOS audit with VoiceOver for what the Mac needs.

b8e audit is a different tool from b8e scan and b8e ci. scan reads your source; ci gates a diff on that scan; an audit runs your product and observes it. Reach for audit when a finding only shows up in the running app: focus order, a live region that never announces, a modal that traps nobody.

An audit runs the journeys defined for a project in the dashboard, so first pick a project and list its journeys:

Terminal window
b8e project
b8e list journeys

b8e list journeys prints each journey’s id and name. Nothing to audit means no journeys are defined yet — add them in the dashboard first.

Audit every journey the project has:

Terminal window
b8e audit --journeys all

Or name the ones you want, comma-separated:

Terminal window
b8e audit --journeys jrn_checkout,jrn_signup

To audit a saved group of journeys by id or name:

Terminal window
b8e audit --group "Checkout flow"

By default the audit browser runs headless. To watch it drive the page — useful when a journey fails and you want to see where — add --no-headless.

An audit needs a real browser and a real screen reader on the machine that hosts it. Before a first run, confirm yours is ready:

Terminal window
b8e doctor

b8e doctor reports whether the browser and screen reader an audit depends on are present and launchable, and names what to install if not. It also prints one line for each mobile platform. The Android audit line is covered in Run an Android audit with TalkBack. On macOS, the iOS audit line checks for Xcode 27 or later and a simulator on an iOS 27 or later runtime, and says whether the audit host is downloaded yet, and each connected iPhone gets an iPhone audit line. Run an iOS audit with VoiceOver covers them. No mobile line changes b8e doctor’s exit code, except with --platform <p>, where that platform decides the exit code.

By default an audit reports and exits 0. To make it gate — in a scheduled job, or a release check — set the bar with --fail-on or --max-violations:

Terminal window
b8e audit --journeys all --fail-on serious
b8e audit --journeys all --max-violations 0

--fail-on takes critical, serious, moderate, or minor and fails on any finding at or above that impact. --max-violations fails when the count exceeds n.

In a script there is nobody to answer a prompt. Pass --ci to refuse every prompt and fail instead of asking. In that mode --journeys and a selected project are required — an audit that cannot resolve what to run should stop, not guess:

Terminal window
b8e audit --ci --project prj_your_project_id --journeys all --fail-on serious

--ci does not change who the audit runs as. b8e audit runs as a person, so it needs a b8e auth login session on the machine that runs it. BINCLUSIVE_API_KEY does not authenticate an audit: with no session, the command exits 7 (Not authenticated) even when the key is set. That key is the credential for b8e ci, which gates a pull request on a scan of your source.

So a --ci audit runs only where someone has already signed in, such as a script on your own machine. A hosted CI runner starts with no session, and b8e auth login cannot run there because it needs a person at a terminal. To audit without anyone’s machine, run the audit in the cloud: where your project offers cloud audits, start one from the project’s Audits → New audit page in the dashboard. It runs on a machine Binclusive hosts.

A long journey set can outlast a default timeout — bound it explicitly with --timeout (e.g. --timeout 10m).

An audit you started and no longer want:

Terminal window
b8e audit stop run_123

The run id is printed when the audit starts.

For machine-readable output, ask for json or sarif and write it to a file:

Terminal window
b8e audit --journeys all --format sarif --output audit.sarif

Findings from a run also land in the project’s dashboard, where each becomes a violation ticket you can inspect with b8e ticket.

For every flag b8e audit accepts, see the audit reference.