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.
Before you start
Section titled “Before you start”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 ascom.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.
Check your Mac is ready
Section titled “Check your Mac is ready”b8e doctorLook for the iOS audit line:
✓ iOS audit readynames the Xcode, the simulator an audit would pick, and the audit host.· iOS audit: no Xcode is selectedmeans 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 textb8e auditwould print. Fix a failed check below covers each one.
Below it, each iPhone connected to this Mac gets a line:
✓ iPhone connectednames the phone and says to connect the team in Settings › iPhones, then runb8e auditto 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 orderb8e auditchecks them: paired, Developer Mode, iOS 27 or later, then unlocked.· iPhone audit: no iPhone is connectedmeans 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.
Run it
Section titled “Run it”Select an iOS project with b8e project, then run its journeys as you would for web:
b8e audit --journeys allThe 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.
Watch a run
Section titled “Watch a run”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.
Choose the device
Section titled “Choose the device”With --device, name an iPhone or a simulator by its name or its UDID:
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--deviceor setBINCLUSIVE_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 runStart from the screen already open
Section titled “Start from the screen already open”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:
b8e audit --journeys jrn_123 --resumeYour 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 skippedAnother 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.
The audit host
Section titled “The audit host”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.
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
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:
b8e audit --journeys all --build-target 2.3.1/a1b2c3Audit on an iPhone
Section titled “Audit on an iPhone”Use an iPhone when your app is only on the App Store or TestFlight, or when you want to hear it on real hardware.
Set up the Mac and the phone once
Section titled “Set up the Mac and the phone once”- 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.
- 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.
- Turn on Developer Mode on the phone in Settings › Privacy & Security › Developer Mode. The phone restarts; confirm when it asks.
- 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.
- 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.
The first run on a phone
Section titled “The first run on a phone”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.
Develop the Swift host locally
Section titled “Develop the Swift host locally”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 with | What 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 with | Open Xcode › Settings › Apple Accounts and add your Apple Account. |
Xcode isn't signed in to your Apple Account | Open Xcode › Settings › Apple Accounts, click Sign In… beside your account, then re-run. |
the iOS audit host did not build for | Read 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 .xctestrun | Re-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 ended | Check 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 within | Read the last lines of the host’s xcodebuild output to find what stopped it. |
What differs from a simulator
Section titled “What differs from a simulator”- 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.
Audit an iPhone from Windows or Linux
Section titled “Audit an iPhone from Windows or Linux”Start with:
b8e doctor --platform ios --fixOn 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:
- Install Python 3.12 and pymobiledevice3. On Windows the CLI runs
py -3.12 -m pymobiledevice3, elsewherepython3 -m pymobiledevice3. SetBINCLUSIVE_PYMOBILEDEVICE3if your command differs. - Connect and unlock the phone, enable Developer Mode, and keep it awake as described above.
- 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.
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 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.
Fix a failed check
Section titled “Fix a failed check”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 with | What to do |
|---|---|
no Xcode is selected | Install 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 later | Install Xcode 27 or later and select it the same way. |
no simulator can run VoiceOver under test | Install an iOS 27 or later runtime in Xcode › Settings › Components, and create an iPhone on it. |
the simulator you named cannot run VoiceOver under test | The 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 by | Pick 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 in | More 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 booting | Boot 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 computer | Unlock the phone, tap Trust when it asks about this computer, and enter its passcode. |
<iPhone> has Developer Mode off | Turn it on in Settings › Privacy & Security › Developer Mode, then let the phone restart. |
<iPhone> runs iOS <version>, and XCTest drives VoiceOver only from iOS 27 | Update the phone to iOS 27 or later, or audit on a simulator. |
<iPhone> can't be reached | Connect the phone to this computer with a cable and unlock it. |
<iPhone> is locked | Unlock the phone, and set Settings › Display & Brightness › Auto-Lock to Never while audits run. |
None of your organizations has an Apple team connected | An admin connects the team in Settings › iPhones, then re-run b8e audit. |
<iPhone> doesn't trust the developer certificate of | On the phone open Settings › General › VPN & Device Management, tap your team under Developer App, tap Trust, then re-run. |
`<command>` could not be run | Install pymobiledevice3, or set BINCLUSIVE_PYMOBILEDEVICE3 to the command that starts it. |
`pymobiledevice3 <command>` failed | The 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 launcher | Set it to xcode or pymobiledevice3, or unset it. |
the iOS audit host did not answer on port | The 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 identifier | Set the bundle identifier in project settings. |
<your bundle identifier> is not installed on | On 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 on | The 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 launched | The 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 obtained | The 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 unpack | The 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 start | The 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.