Run an Android audit with TalkBack
If your project is an Android app, b8e audit runs its journeys on a real Android device or
emulator with TalkBack switched on, and reports what TalkBack said at each step. This guide covers
what the device needs, how the CLI picks a device, and how to fix a failed device check. The
journey flags --journeys, --group, --fail-on and --ci work as they do for web, and
Run an audit of your journeys covers them.
Before you start
Section titled “Before you start”The CLI checks each of these before it runs a journey. A missing item refuses the run, except the app identifier in the first item: without one the run goes ahead with the weaker checks it describes.
- An Android project. The project’s platform in the dashboard is
android. Set the project’s app identifier in project settings: the app’s package name, such ascom.example.shop. Without one, the CLI can only confirm that some app is installed, not yours, and cannot read the build target off the device. adb. The CLI looks forplatform-tools/adbunderANDROID_HOME, thenANDROID_SDK_ROOT, then the SDK’s default install location for your OS, and finally triesadbon yourPATH.- A reachable device. Either a phone connected over USB with debugging on, or a running
emulator.
adb devices -lshould list it in statedevice. - The Binclusive audit agent,
com.binclusive.auditagent, on the device. The run installs it for you, as The audit agent describes. - TalkBack. Google’s TalkBack comes with the Google apps; Samsung phones ship Samsung’s own
TalkBack, and the run drives either one. When a device has both, the run uses Google’s. An AOSP
emulator image has no TalkBack, so create the emulator from a
google_apissystem image. - The agent as the text-to-speech engine. The run sets this itself, as Device settings the run borrows describes, and checks it held.
- The app under test, installed on the device under the identifier your project names.
Check the device is ready
Section titled “Check the device is ready”b8e doctorLook for the Android audit line:
✓ Android audit device readymeans a device is attached and passes the device checks.· Android audit: no Android device is runningmeans the check was skipped because no device is attached. If AVDs exist on disk, it lists them and prints theemulator -avd <name>command that boots one.· Android audit:followed by anadbmessage meansadbcould not be found.✗ Android audit — …names the first check the device fails, with the same textb8e auditwould print. Fix a failed device check below covers each one.· Android audit: this device is still holding … of the audit's device settingsmeans a run ended before it could put its settings back, for example because it was killed. An audit still runs on that device. The line prints theadb shell settingscommand that clears each setting;b8e doctor --fixdoes not run them, because nothing records what the settings were before.· Android audit: could not read whether a run left this device holding …means theadb shell settings getthe line names failed, so doctor cannot say whether a run left any settings behind. An audit reads those settings itself before it starts, and stops if it cannot.
b8e doctor does not fail a device on the settings a run borrows, such as the text-to-speech engine:
the run sets those itself and checks they held.
b8e doctor checks the device without knowing your project, so it only confirms that some app
other than the audit agent is installed, not that it is yours. The Android line also does not change
b8e doctor’s exit code, which reflects the browser and desktop screen-reader checks for web
audits, except with --platform <p>, where that platform decides the exit code. Read the line itself.
Run it
Section titled “Run it”Select an Android project with b8e project, then run its journeys as you would for web:
b8e audit --journeys allThe run announces the device it drives:
Mobile audit (android): driving TalkBack over adb on Pixel 8 (shiba) [38011FDJH00AB1]Choose the device
Section titled “Choose the device”With --device, name an attached device by its serial or its model, or a stopped AVD by name:
b8e audit --journeys all --device emulator-5554b8e audit --journeys all --device Pixel_8_API_35Without --device, the CLI uses ANDROID_SERIAL if it is set. With neither, it picks the one
running device. If several devices are running, or none are and AVDs exist on disk, an interactive
run asks you to pick, listing AVDs as not running. A non-interactive run refuses and names what
it found.
A stopped AVD is booted only in an interactive run. The CLI starts the emulator and waits up to
180 seconds for Android to finish booting. A run with --ci, --non-interactive or --yes, a run
in CI, or a run with no terminal never starts an emulator. It refuses and prints the command to
boot the AVD yourself. Boot it, let it finish, then run again. If a run booted an AVD and then
fails a device check, the emulator is left running so you can fix it there.
The audit agent
Section titled “The audit agent”Each run first checks that the device carries the audit agent version this CLI expects. If it is
missing or out of date, an interactive run asks before it downloads the APK from
cdn.binclusive.io and installs it. The CLI checks the download against its published sha256
digest before installing it. A non-interactive run installs it without asking and prints a line
saying so. The agent stays installed after the audit.
If you decline, nothing is downloaded and the run stops, printing the curl and adb install
commands to install it yourself.
Device settings the run borrows
Section titled “Device settings the run borrows”To drive TalkBack, the run turns on accessibility, touch exploration, TalkBack and the agent’s own
accessibility service, and makes the agent the default text-to-speech engine. It prints each
setting it changed, with the old and new value, and puts every one back when the run ends,
including when you stop it with Ctrl-C, close its terminal, or end it with kill. If a setting
cannot be put back, the CLI prints the adb shell settings command that restores it. If a setting
does not take, the run stops before any journey, naming the setting, the value it read back and
the value it needs.
A run that is killed outright, with kill -9, cannot put anything back. b8e doctor reports a
device left in that state, as Check the device is ready describes.
Set the build target
Section titled “Set the build target”Each run is recorded against a build of your app. By default the CLI reads the installed app’s
versionName and versionCode from the device, records them as <release>/<dist>, and prints
the build target it read. To record a different build, such as a commit SHA only your CI knows,
pass it yourself:
b8e audit --journeys all --build-target 2.3.1/a1b2c3If the CLI cannot read a version off the device and you passed no --build-target, it says so and
runs without a build target. --build-target is for mobile projects only; a web audit refuses it.
Start from the screen already open
Section titled “Start from the screen already open”Each journey normally force-stops the app under test and launches it again from its start screen.
If you have already opened the app on the device and gone to the screen you want checked, for
example after logging in, pass --resume to start from that screen instead:
b8e audit --journeys jrn_123 --resumeThe app under test must already be in the foreground on the device the run drives, so pick that
device with --device if more than one is running. The run does not force-stop or relaunch the
app, and it skips the journey’s entry steps: neither the deep link nor the tap path runs, and the
deep-link check is not made. The setup log names the screen it found:
setup: resumed in place on com.example.shop/.ui.cart.CartActivity; no force-stop, no launch, journey entry skippedIf another app is in front, the run stops instead of auditing it, and names both apps:
--resume found com.android.chrome in the foreground, not com.example.shop, the app under test.
If no app is in front, it says --resume found no app in the foreground. Either way it never
falls back to launching the app, because that would throw away the screen you set up. Bring your
app to the front and run again, or drop --resume. The project needs its app identifier set, as
Before you start describes, so the run can tell your app from another.
Only the first journey of a run starts from the open screen. When you run several, the rest force-stop and launch the app as usual, because the first one leaves it wherever it ended.
--resume works for local runs only. A cloud run boots a fresh device with nothing on screen, so
--resume with --cloud is refused, and so is --resume on a web project. An iOS project takes
--resume too; see Run an iOS audit.
What a run produces
Section titled “What a run produces”A run prints one report covering every journey, in the same pretty, json and sarif formats
as a web audit, and its findings land in the project’s dashboard as violation tickets. A finding
names the WCAG success criterion it fails, its impact, what TalkBack said as evidence, and a fix.
The agent attaches the device screenshot from its last announcement before it recorded the
finding. --fail-on and --max-violations gate the exit code exactly as they do for web.
To learn how the agent walks the app and judges what it hears, see About TalkBack audits.
Fix a failed device check
Section titled “Fix a failed device check”A failed device check prints one message saying what is missing and what to do. Find it below by how it starts. Other refusals, such as a declined agent install or a stopped AVD in a non-interactive run, are not listed here; each prints its own remedy.
| The message starts with | Failure mode | What to do |
|---|---|---|
`adb` could not be run | adb_unresolved | Install the Android SDK platform-tools, or point ANDROID_HOME or ANDROID_SDK_ROOT at the SDK root that holds them. The message lists every location it searched. |
no adb device is reachable | adb_disconnected | Attach an emulator or device, then re-run. adb devices -l should list one in state device. |
This device has not been unlocked since it booted | device_locked | Unlock the device with its PIN, pattern or password, then re-run. Until the first unlock, Android binds no accessibility service that is not encryption-aware, and the audit agent’s service is not. Dismissing the keyguard or waking the screen does not unlock it. |
the on-device audit agent … is not installed | agent_absent | Run b8e audit against the device. It downloads and installs the agent, as The audit agent describes. |
the on-device audit agent … is <version>, not the <version> this CLI reads | agent_stale | Run b8e install-android-audit-agent, or b8e audit, which upgrades the agent after asking. On a cloud runner, re-bake the Android image. |
No TalkBack is installed on this device | talkback_absent | The device has neither Google’s nor Samsung’s TalkBack. The message lists the accessibility services it does have. The audit switches TalkBack on but cannot install it. Install Google TalkBack (Android Accessibility Suite on Google Play). On an emulator, use a google_apis system image. Then re-run. |
`adb shell` cannot read | transcript_unreadable | The CLI cannot read the folder where the agent writes what TalkBack said. Reinstall the agent APK so it recreates that folder, and check the device is not remapping app external storage. |
TalkBack's speech does not reach the transcript | speech_uncaptured | Before the walk, TalkBack is asked to announce a check phrase, and it never reached the agent’s transcript. Everything else holds, so TalkBack is most likely still bound to the speech engine of an agent that was reinstalled under it. Reinstall the agent APK with b8e install-android-audit-agent, switch TalkBack off and on again under Settings › Accessibility › TalkBack, then re-run. b8e doctor does not run this check, because it does not switch TalkBack on. |
<your app identifier> is not installed on the device | app_install_failed | Install that build before auditing, or correct the app identifier in project settings. |
the journey's entry deep link resolves to no activity | deep_link_unresolved | Check the deep-link URL, and that your app declares an intent-filter for it. |
the journey's tap path … did not reach its screen | tap_path_unresolved | A label in the tap path matched no tappable control on the screen it was tapped from. Give each tap the text TalkBack reads for that control, in the order the taps happen. |
The deep-link check runs per journey, and only for journeys that start from a deep link. A failure there fails that journey and the rest still run. A tap path is checked one tap at a time as its journey starts, and a label that matches nothing stops that journey before the audit reads any screen. Every other check runs once before any journey starts and stops the whole run.
Fix a TalkBack crash during the walk
Section titled “Fix a TalkBack crash during the walk”When a move hears nothing, the audit checks that TalkBack is still bound. A crashed TalkBack makes every later move silent, and that silence would read as accessibility failures in your app. So the run stops with a device error instead of reporting findings.
| The message starts with | Failure mode | What to do |
|---|---|---|
TalkBack stopped during the walk | talkback_crashed_mid_walk | Turn TalkBack off and on again under Settings › Accessibility › TalkBack, then re-run. On an emulator, TalkBack can crash while it describes images. Before you re-run, open TalkBack settings › Automatic descriptions › Describe text in images, and choose Don’t describe images. |
For every flag b8e audit accepts, see the audit reference.