Skip to content

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.

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 as com.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 for platform-tools/adb under ANDROID_HOME, then ANDROID_SDK_ROOT, then the SDK’s default install location for your OS, and finally tries adb on your PATH.
  • A reachable device. Either a phone connected over USB with debugging on, or a running emulator. adb devices -l should list it in state device.
  • 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_apis system 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.
Terminal window
b8e doctor

Look for the Android audit line:

  • ✓ Android audit device ready means a device is attached and passes the device checks.
  • · Android audit: no Android device is running means the check was skipped because no device is attached. If AVDs exist on disk, it lists them and prints the emulator -avd <name> command that boots one.
  • · Android audit: followed by an adb message means adb could not be found.
  • ✗ Android audit — … names the first check the device fails, with the same text b8e audit would print. Fix a failed device check below covers each one.
  • · Android audit: this device is still holding … of the audit's device settings means 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 the adb shell settings command that clears each setting; b8e doctor --fix does not run them, because nothing records what the settings were before.
  • · Android audit: could not read whether a run left this device holding … means the adb shell settings get the 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.

Select an Android project with b8e project, then run its journeys as you would for web:

Terminal window
b8e audit --journeys all

The run announces the device it drives:

Mobile audit (android): driving TalkBack over adb on Pixel 8 (shiba) [38011FDJH00AB1]

With --device, name an attached device by its serial or its model, or a stopped AVD by name:

Terminal window
b8e audit --journeys all --device emulator-5554
b8e audit --journeys all --device Pixel_8_API_35

Without --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.

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.

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.

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:

Terminal window
b8e audit --journeys all --build-target 2.3.1/a1b2c3

If 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.

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:

Terminal window
b8e audit --journeys jrn_123 --resume

The 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 skipped

If 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.

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.

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 withFailure modeWhat to do
`adb` could not be runadb_unresolvedInstall 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 reachableadb_disconnectedAttach an emulator or device, then re-run. adb devices -l should list one in state device.
This device has not been unlocked since it booteddevice_lockedUnlock 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 installedagent_absentRun 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 readsagent_staleRun 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 devicetalkback_absentThe 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 readtranscript_unreadableThe 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 transcriptspeech_uncapturedBefore 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 deviceapp_install_failedInstall that build before auditing, or correct the app identifier in project settings.
the journey's entry deep link resolves to no activitydeep_link_unresolvedCheck the deep-link URL, and that your app declares an intent-filter for it.
the journey's tap path … did not reach its screentap_path_unresolvedA 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.

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 withFailure modeWhat to do
TalkBack stopped during the walktalkback_crashed_mid_walkTurn 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.