iOS native testing on the agent

Run native iOS tests through the local agent: prerequisites, the one-time WebDriverAgent build, choosing a simulator, and .app versus .ipa artifacts.

The honest headline: iOS requires your Mac or your device-cloud account. Unlike web and Android, iOS has a hard, non-negotiable dependency on macOS — there is no way around it. If no Mac is in the loop, there is no iOS, full stop.

Vera drives native iOS apps through Appium's xcuitest driver, which builds and code-signs WebDriverAgent with xcodebuild. xcodebuild and the iOS simulators ship only inside Xcode, which runs only on macOS. So a native iOS run needs one of exactly two things:

A Mac running vera-agent with Xcode + simulators (this document), or
A device cloud account (BrowserStack / LambdaTest) — the server-side path, see Test engines → Native mobile.

This page covers path (1): running iOS tests against simulators on your own Mac via the agent.

1. Prerequisites

Requirement	Why	How
macOS	Xcode is macOS-only; no Xcode ⇒ no iOS	—
Full Xcode (not just Command Line Tools)	The `xcuitest` driver builds WebDriverAgent with `xcodebuild`	Install from the App Store, then `sudo xcodebuild -license accept` and `xcode-select -s /Applications/Xcode.app`
iOS simulators	The run target	Xcode ▸ Settings ▸ Platforms (or Window ▸ Devices and Simulators)
Appium 2 + the `xcuitest` driver	Drives the app	`npm i -g appium && appium driver install xcuitest`
A free Apple ID	Signs WebDriverAgent for simulators and personal devices	Sign in via Xcode ▸ Settings ▸ Accounts; simulators need no paid account

Run vera-agent doctor to verify all of the above with actionable fix-its. On a Mac it adds these iOS lines:

Xcode — the selected developer directory.
simulators — count of available simulators.
xcodebuild — whether xcodebuild -version runs (the real readiness signal). Note: the first iOS session builds WebDriverAgent — slow, but one-time per Xcode version.
iOS devices — best-effort count of real attached devices (display only; runs target simulators).

The mobile checks are required (they fail doctor) only when this agent advertises the iOS capability — a desktop-only agent never fails over a missing simulator.

2. WebDriverAgent: the one-time first-run build

The xcuitest driver works by compiling WebDriverAgent (a helper app) and installing it on the simulator, then talking to it. The first iOS session on a machine (per Xcode version) triggers this xcodebuild build + sign step, which is slow (often a minute or more) and prints a lot of Xcode output. This is normal and one-time — subsequent runs reuse the built WDA.

Simulators are signed with Xcode's free personal team — no paid Apple Developer account, no provisioning profile.
Vera does not pre-build WebDriverAgent for you; Appium builds it on demand. If the build fails, Appium's own error surfaces verbatim in the run — usually an Xcode licence not accepted, a Command-Line-Tools-only install, or a signing team not selected.

3. Choosing a simulator (`deviceProfile`)

Set the test's mobile device profile to a simulator name, e.g. iPhone 15. On an iOS lease the agent:

Lists available simulators (xcrun simctl list devices available --json).
Resolves your deviceProfile by name (case-insensitive). When several match, it prefers one that is already booted, otherwise the one on the newest iOS runtime.
Boots the chosen simulator if none is running (xcrun simctl boot), and waits for it to reach the Booted state (bounded timeout).
Passes the resolved udid / deviceName / platformVersion to Appium as appium:udid etc, so the session pins to exactly that device.

If no simulator matches the requested name, the run fails with an actionable error that lists the simulators you do have — copy an exact name from that list into your device profile. Leave the profile blank to let Appium/Xcode pick a default device.

4. App artifacts: `.app` vs `.ipa`

An iOS simulator cannot install a device-signed .ipa — those are built for real ARM devices with a provisioning profile. For a simulator run the honest artifact is either:

a simulator-built .app (typically zipped), or
a development .ipa built for the simulator.

Vera passes your uploaded artifact through unchanged as appium:app — it does not silently transform it. If the artifact is the wrong kind for the target, Appium's install error surfaces verbatim in the run so you can see exactly what happened. Upload a simulator build for simulator runs.

5. Real devices (out of scope for now)

Running on a real iPhone/iPad additionally requires, beyond everything above:

an Apple Developer account (the paid one, ~$99/yr for anything beyond a personal device), and
provisioning — a signing team, a provisioning profile, and the device registered/trusted.

vera-agent doctor will display attached real devices (best-effort, via xctrace list devices), but agent runs in this phase target simulators only. Real-device execution is a future capability — until then, use simulators locally or a device cloud for real hardware.

6. Alternatives to a local Mac

If you don't have a Mac to dedicate to the agent:

CI runner (macOS) — run the agent on a hosted macos-* CI runner in drain mode. See the CI-rider guide for the composite Action and cost math; use a macos-latest runner so Xcode + simulators are present.
Device cloud (Team+) — the server-side path (BrowserStack / LambdaTest) runs on the vendor's real devices/simulators with your credentials, no local Mac needed. Configure it in the dashboard's device-cloud settings; see Test engines → Native mobile.