Skip to content

Run an iOS audit with VoiceOver

If your project is an iOS app, b8e audit runs its journeys on an iOS Simulator or on an iPhone connected to your computer, with VoiceOver switched on, and reports what VoiceOver said at each step. For a phone audit, an admin connects the Apple team in Settings › iPhones, then you run b8e audit. Mac, Windows and Linux use the same server preparation and pymobiledevice3 execution workflow. This guide covers device setup, selection and failed checks. 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, and refuses the run if one is missing.

  • For a simulator, a Mac with Xcode 27 or later, selected. VoiceOver can only be driven under test from iOS 27.
  • For a phone, Python 3.12 and pymobiledevice3. Mac phone discovery and installation also use Xcode’s device tools.
  • A device on iOS 27 or later. Either a simulator on an iOS 27 or later runtime (install the runtime in Xcode › Settings › Components, and create an iPhone on it if Xcode did not), or an iPhone on iOS 27 or later set up as Audit on an iPhone describes.
  • An iOS project. The project’s platform in the dashboard is ios, and its app identifier is your app’s bundle identifier, such as com.example.shop. The CLI launches the app by that identifier, so a project without one is refused.
  • The app under test, installed on the device, under that identifier. On a simulator: xcrun simctl install <simulator-udid> <path/to/YourApp.app>. On an iPhone, install it from the App Store, TestFlight or Xcode.
Terminal window
b8e doctor

Look for the iOS audit line:

  • ✓ iOS audit ready names the Xcode, the simulator an audit would pick, and the audit host.
  • · iOS audit: no Xcode is selected means the check was skipped because this Mac has no Xcode, or only the Command Line Tools.
  • ✗ iOS audit — … names the first check that fails, with the same text b8e audit would print. Fix a failed check below covers each one.

Below it, each iPhone connected to this Mac gets a line:

  • ✓ iPhone connected names the phone and says to connect the team in Settings › iPhones, then run b8e audit to prepare its host. An organization admin connects the team. Doctor checks the connected phone; it does not prepare or sign a host.
  • ✗ iPhone audit — … names the first check that fails, in the order b8e audit checks them: paired, Developer Mode, iOS 27 or later, then unlocked.
  • · iPhone audit: no iPhone is connected means there is nothing to check. Simulator audits don’t need a phone.

b8e doctor doesn’t know your project, so it doesn’t check that your app is installed. The iOS and iPhone lines don’t change b8e doctor’s exit code, except with --platform <p>, where that platform decides the exit code. Read the lines themselves.

Select an iOS 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, and boots a simulator if it is not running:

Mobile audit (ios): driving VoiceOver on iPhone 17 (iOS 27, 7E491066-81AC-48B3-BCC0-987839B206EF)

On a simulator, before each journey the CLI quits your app, resets its privacy permissions and launches it again, so the journey meets your app’s permission prompts the way a new user does. On an iPhone it launches your app again but leaves its permissions as they are.

To stop a run, press Ctrl-C. On a simulator, the CLI restores VoiceOver and its Quick Nav keys. Standard phone execution turns VoiceOver off when the host stops. The CLI also stops the host when you close the terminal or end it with kill. That usually takes a few seconds, and longer when the host is still starting or in the middle of a long move such as a rotor search. Press Ctrl-C again to quit at once, which can leave VoiceOver on.

On a simulator, you can’t watch a run on your Mac. The CLI boots the simulator headless, with no window. Xcode 27 ships DeviceHub.app instead of Simulator.app, and whether DeviceHub shows a booted simulator’s screen is unconfirmed. On an iPhone, watch the phone itself.

The run’s page in the dashboard is the closest you get. Every action the agent takes returns a screenshot, and while the run goes on the page shows the latest one. After the run, two things are kept for review:

  • The recording or replay, on the run’s page. Standard iPhone runs on Mac, Windows and Linux get a frame replay when ffmpeg is installed. It stitches together the screenshots returned after each action, with no audio or motion between steps. Without ffmpeg the audit still completes and prints why it has no replay. The CLI uploads the recording when the run ends and keeps no local copy, so if the upload fails it prints Run <run id>'s screen recording could not be uploaded, so its run page has none: and the reason.
  • Each finding’s screenshot, on its violation ticket, from VoiceOver’s last announcement before the agent recorded the finding. What a run produces covers the findings.

With --device, name an iPhone or a simulator by its name or its UDID:

Terminal window
b8e audit --journeys all --device "iPhone 17"

Without --device, the CLI uses BINCLUSIVE_IOS_DEVICE if it is set. BINCLUSIVE_IOS_SIMULATOR, its old name, still works and prints a line asking you to rename it. With neither, it looks for a ready device: an iPhone that is connected, unlocked and set up, or a simulator that is running on iOS 27 or later.

  • With one ready device, it uses that device without asking.
  • With several, it asks you to pick one. In a script, or with --ci, it refuses and lists them, so pass --device or set BINCLUSIVE_IOS_DEVICE.
  • With none, it boots a simulator that can run VoiceOver, preferring an iPhone and then the newest iOS.

A connected iPhone that is not ready is skipped, with a line that says why and what to do. A paired iPhone that isn’t connected is skipped without one.

Skipping an iPhone: Ayşe’s iPhone (iPhone 13, iOS 27.0.1, 00008110-000A1C2E3E91801E) is locked — unlock it, and set Settings › Display & Brightness › Auto-Lock to Never while audits run

Each journey normally quits your app and launches it again from its start screen. If you have already opened the app on the simulator or iPhone 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

Your app must already be open on the device the run drives, so pick that device with --device if more than one is ready. The run does not quit, reset or relaunch the app, and on a simulator it leaves the app’s privacy permissions as they are. It skips the journey’s entry steps: neither the deep link nor the tap path runs. The setup log says it resumed and the state it found the app in:

setup: resumed in place on com.example.app (the host found it runningBackground); no terminate, no privacy reset, no launch, journey entry skipped

Another app in front is not an error. iOS gives the CLI no way to read which app is in front, so the run asks only whether your app is running, then brings it forward on the screen you left it on, without relaunching it.

If your app is not running, the run stops instead of launching it, because a launch would throw away the screen you set up. It names the app and the device: --resume found com.example.app, the app under test, not running on iPhone 17. Open your app on the screen to audit and run again, or drop --resume. iOS can also end an app that sat in the background for a while to free memory, and that reads the same way.

Only the first journey of a run starts from the open screen. When you run several, the rest quit 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.

VoiceOver is driven by a small test host that runs beside your app on the device. On a simulator, the first iOS audit downloads the host version this CLI expects from cdn.binclusive.io, checks the download against its published sha256 digest, and unpacks it into ~/.cache/b8e/ios-host/<version>. It prints a line saying so. Later runs use that copy. The download is a few hundred kilobytes and is written only to that folder. Each journey installs the host and its UI-test runner on the simulator it drives, as any XCUITest run does.

On an iPhone, the CLI prepares a signed host through the phone’s organization, verifies and caches the signed pair, then installs and launches it. Audit on an iPhone covers that.

Each run is recorded against a build of your app. By default the CLI reads the installed app’s CFBundleShortVersionString and CFBundleVersion off the iPhone or simulator, records them as <release>/<dist>, and prints the build target it read. To record a different build, pass it yourself:

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

Use an iPhone when your app is only on the App Store or TestFlight, or when you want to hear it on real hardware.

  1. Connect the organization’s Apple team. An organization admin connects it in Settings › iPhones. Phone ownership selects the team, independently of the project being audited. Install Python 3.12 and pymobiledevice3 on the Mac for phone installation and execution.
  2. Connect the iPhone with a cable, unlock it, and tap Trust when it asks whether to trust this computer. Enter the phone’s passcode when asked.
  3. Turn on Developer Mode on the phone in Settings › Privacy & Security › Developer Mode. The phone restarts; confirm when it asks.
  4. Switch on the rotor items the audit uses, in Settings › Accessibility › VoiceOver › Rotor: Links, Buttons, Form Controls, Text Fields, Tables, Lists, Images and Landmarks. Headings and Containers are on already. A VoiceOver user finds items of one type by turning the rotor, and on an iPhone the rotor offers an item only when it is switched on there and applies to what is on screen. The audit doesn’t change these settings for you, because they are your phone’s own. A search for an item the current screen doesn’t offer fails with a line that names it. That can happen with the item switched on: a native screen may not offer Buttons or Text Fields, and the tester moves with next, previous, jump or explore instead.
  5. Keep the phone awake during audits. Set Settings › Display & Brightness › Auto-Lock to Never while audits run, and keep the phone unlocked and on its cable. A locked phone can’t launch your app, and the run refuses it.

Connect the team in Settings › iPhones, then run b8e audit. Every run asks the server to prepare the phone’s host. If a new phone has several eligible organizations, the CLI asks which organization should own it. A registered phone always uses its owning organization.

The CLI verifies and caches the two signed IPAs, installs them, mounts the developer image, and starts the host over USB with pymobiledevice3 on Mac, Windows and Linux. Later runs validate authorization and signing status with the server before reusing cached files. A server refusal stops the run.

If iOS asks you to trust the developer, open Settings › General › VPN & Device Management on the phone, trust the connected organization’s team, and re-run.

On a Mac, set BINCLUSIVE_IOS_HOST_DIR to a source checkout containing AuditHost.xcodeproj to run unpublished Swift changes. This explicit developer route uses xcodebuild for build-for-testing and execution, and an Apple account in Xcode › Settings › Apple Accounts. With several teams, choose one in an interactive terminal. The CLI builds without a separate consent question. Unset the variable to return to server preparation. This route can export XCTest’s native screen recording from the result bundle after the run. Simulator runs need no Apple team.

Signing and build errors below apply only when BINCLUSIVE_IOS_HOST_DIR selects local Swift development:

The message starts withWhat to do
`xcodebuild -version` failed:Read Xcode’s message. If it asks you to accept its license, run sudo xcodebuild -license accept.
Xcode has no Apple team to sign the iOS audit host withOpen Xcode › Settings › Apple Accounts and add your Apple Account.
Xcode isn't signed in to your Apple AccountOpen Xcode › Settings › Apple Accounts, click Sign In… beside your account, then re-run.
the iOS audit host did not build forRead the last lines of Xcode’s output. Check the account is signed in and can sign a development build.
xcodebuild reported success but wrote no .xctestrunRe-run; the CLI rebuilds the host when it finds no complete build.
Xcode rebuilt the iOS audit host for <iPhone> but kept the signing profile that endedCheck your team is signed in under Xcode › Settings › Apple Accounts, then re-run.
the iOS audit host exited or the iOS audit host was not ready withinRead the last lines of the host’s xcodebuild output to find what stopped it.
  • VoiceOver in English or Turkish is read. Other languages are untested: an action can report that it failed when VoiceOver spoke its result in another language.
  • Your app’s permissions are left as they are, so the journey meets whatever the app already allowed. To hear a permission prompt, delete and reinstall the app on the phone first.
  • The Mac can’t send your app a test notification, so a journey step that asks for one is refused.
  • Standard phone execution requires a tap path for the journey’s entry. pymobiledevice3 launches an app by its bundle identifier and cannot pass an entry link.

About VoiceOver audits covers what the agent hears differently on a phone.

Start with:

Terminal window
b8e doctor --platform ios --fix

On Windows this installs missing Python 3.12, pymobiledevice3, the Apple USB driver through iTunes, and optional ffmpeg. Windows asks for admin when installing the driver. You don’t need to open iTunes. If doctor installs anything, open a new terminal and run b8e doctor --platform ios again to verify it. A stopped Apple Mobile Device Service needs a restart or the administrator command doctor prints.

Connect and unlock the phone. Tap Trust at Trust This Computer and enter its passcode. Doctor can reveal a missing Developer Mode switch. Turn it on in Settings › Privacy & Security › Developer Mode; after the phone restarts, unlock it and tap Turn On.

Set once on the phone: Settings › Accessibility › VoiceOver › Rotor — Links, Buttons, Form Controls, Text Fields, Tables, Lists, Images, Landmarks on; Display & Brightness › Auto-Lock › Never.

Windows and Linux use the same server preparation, cache and preinstalled execution workflow as Mac phone audits. A simulator still needs Xcode on a Mac. On Linux, doctor prints manual install instructions. If automatic setup fails, use these manual steps:

  1. Install Python 3.12 and pymobiledevice3. On Windows the CLI runs py -3.12 -m pymobiledevice3, elsewhere python3 -m pymobiledevice3. Set BINCLUSIVE_PYMOBILEDEVICE3 if your command differs.
  2. Connect and unlock the phone, enable Developer Mode, and keep it awake as described above.
  3. Have an admin connect the team in Settings › iPhones, then run b8e audit.

Phone execution notes:

  • With ffmpeg on PATH, the CLI stitches the screenshots the agent saw at each step into an MP4 replay on the run’s page. On Windows, install it with winget install Gyan.FFmpeg, then reopen your terminal. On Linux, install ffmpeg with your package manager. The replay has no audio or motion between steps. Without ffmpeg, the audit still completes and prints one line explaining why it has no replay.
  • On all three platforms, standard phone execution refuses a journey that starts from a link. Start such a journey from a tap path instead.
  • With pymobiledevice3, the CLI can’t read whether VoiceOver was on before the run. The host turns it on for the run and off after it.
  • Reading whether the phone is locked through pymobiledevice3 works on iOS 27.2 or later. On an older phone the run stops at the lock check.

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 VoiceOver said as evidence, and a fix. The agent attaches the screenshot from VoiceOver’s 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 VoiceOver audits.

A failed check prints one message saying what is missing and what to do. Find it below by how it starts. <iPhone> stands for the phone’s name, model, iOS version and UDID. For local build and signing failures, see Develop the Swift host locally. Standard phone audits prepare the host through the organization connected in Settings › iPhones.

The message starts withWhat to do
no Xcode is selectedInstall Xcode 27 or later from the App Store, then select it with sudo xcode-select -s /Applications/Xcode.app.
Xcode <version> is selected, and iOS audits need Xcode 27 or laterInstall Xcode 27 or later and select it the same way.
no simulator can run VoiceOver under testInstall an iOS 27 or later runtime in Xcode › Settings › Components, and create an iPhone on it.
the simulator you named cannot run VoiceOver under testThe simulator you passed with --device or BINCLUSIVE_IOS_DEVICE is on an iOS older than 27. The message names it. Pick one on iOS 27 or later from xcrun simctl list devices, or leave both unset so the CLI picks one.
no iPhone or iOS simulator is named or identified byPick a simulator from xcrun simctl list devices or an iPhone from xcrun devicectl list devices, and pass its name or UDID with --device or BINCLUSIVE_IOS_DEVICE.
Multiple devices available and no terminal to ask inMore than one iPhone or simulator is ready. Pass one of the listed devices with --device, or set BINCLUSIVE_IOS_DEVICE.
<simulator> (iOS …) did not finish bootingBoot it yourself with xcrun simctl boot <simulator-udid> and read the error it prints, or pick another one with --device or BINCLUSIVE_IOS_DEVICE.
<iPhone> isn't paired with this computerUnlock the phone, tap Trust when it asks about this computer, and enter its passcode.
<iPhone> has Developer Mode offTurn it on in Settings › Privacy & Security › Developer Mode, then let the phone restart.
<iPhone> runs iOS <version>, and XCTest drives VoiceOver only from iOS 27Update the phone to iOS 27 or later, or audit on a simulator.
<iPhone> can't be reachedConnect the phone to this computer with a cable and unlock it.
<iPhone> is lockedUnlock the phone, and set Settings › Display & Brightness › Auto-Lock to Never while audits run.
None of your organizations has an Apple team connectedAn admin connects the team in Settings › iPhones, then re-run b8e audit.
<iPhone> doesn't trust the developer certificate ofOn the phone open Settings › General › VPN & Device Management, tap your team under Developer App, tap Trust, then re-run.
`<command>` could not be runInstall pymobiledevice3, or set BINCLUSIVE_PYMOBILEDEVICE3 to the command that starts it.
`pymobiledevice3 <command>` failedThe rest is pymobiledevice3’s own message. Check the phone is connected, unlocked and has Developer Mode on, then re-run.
BINCLUSIVE_IOS_LAUNCHER is "<value>", which names no launcherSet it to xcode or pymobiledevice3, or unset it.
the iOS audit host did not answer on portThe signed host was built from another host version than the CLI’s, so it doesn’t listen on the port this run chose. Re-run b8e audit to prepare the expected host version.
this project declares no app identifierSet the bundle identifier in project settings.
<your bundle identifier> is not installed onOn a simulator, install a simulator build with xcrun simctl install. On an iPhone, install the app from the App Store, TestFlight or Xcode. Or correct the app identifier in project settings.
could not check whether <your bundle identifier> is installed onThe rest is devicectl’s own message. Check that the simulator still runs (xcrun simctl list devices booted) or that the iPhone is still connected and unlocked, then re-run.
<your bundle identifier> could not be launchedThe rest is devicectl’s own message. Open the app on the device by hand to check that it launches, then re-run.
the iOS audit host could not be obtainedThe CLI could not download or verify the host. The message names the URL and why; check that this Mac can reach cdn.binclusive.io, then re-run.
the iOS audit host did not unpackThe download could not be unpacked into ~/.cache/b8e/ios-host/<version>. The CLI keeps no partial copy, so re-run to download it again.
the iOS audit host could not startThe rest says why. Either your app did not reach the foreground within 30 seconds, or VoiceOver could not be switched on. Open the app on the device by hand to check that it launches, then re-run.

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