Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Architecture and Setup

Xcode, iOS Simulators and Real iPhones

Prepare a Mac for iOS automation: install Xcode and command line tools, manage simulators with simctl, understand WebDriverAgent and plan real device signing.

iOS automation has a hard requirement that Android does not: you need a Mac with Xcode. The XCUITest driver builds and launches a helper called WebDriverAgent (WDA) on the device, and building iOS software is only possible with Apple's toolchain. Once Xcode is installed, simulators are easy. Real iPhones add a code-signing step that trips up many beginners.

Commands here are for a Mac terminal and are shown read-only; Appium and Xcode cannot run in this page.

Install the toolchain

  1. Install Xcode from the Mac App Store (it is large, so allow time and disk space), and open it once to accept the license and install additional components.
  2. Install the command line tools and point the system to your Xcode:
Terminal
xcode-select --install
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcodebuild -version
  1. Install the Appium driver, as in Installing the Appium Server:
Terminal
appium driver install xcuitest

Optional helpers that some teams use include Carthage (older WebDriverAgent builds), ios-deploy and libimobiledevice for real devices. Current XCUITest driver versions need fewer of these than older ones; follow the driver's own documentation for your version.

Simulators with simctl

Xcode includes iOS Simulator runtimes. The xcrun simctl tool manages them from the terminal:

Terminal
xcrun simctl list devices available
xcrun simctl boot "iPhone 16"
xcrun simctl shutdown all
xcrun simctl install booted /builds/Shop.app
xcrun simctl launch booted com.example.shop
xcrun simctl erase all

Each simulator has a name, an OS version (runtime) and a UDID, a unique identifier like A1B2C3D4-.... In capabilities you can use deviceName and platformVersion, or the exact udid to avoid any ambiguity.

Important points about simulators:

  • Simulator apps are built for the simulator (.app folder, Intel or arm64-simulator slice). You cannot install a device IPA on a simulator.
  • A simulator shares your Mac's network and has no real camera, push notifications through Apple's servers, or cellular.
  • Runtimes are downloaded through Xcode Settings (Platforms); a missing runtime is a classic "no such device" cause.

WebDriverAgent

When a session starts, the XCUITest driver builds WebDriverAgent with xcodebuild and runs it on the target. WDA is a UI test bundle that:

  • Starts a small HTTP server on the device (default port 8100).
  • Uses XCUITest APIs to find elements, tap, swipe and take screenshots.
  • Replies to the driver's commands.

The first build is slow (a minute or more) because Xcode compiles WDA. After that it is cached. You can speed things up by capabilities such as usePrebuiltWDA (reuse a build) or wdaLaunchTimeout, which are covered with the other XCUITest settings in XCUITest Capabilities.

Real iPhones: signing

A real device will only run WDA if it is signed with a valid Apple developer identity. You need:

  • An Apple ID (a free one works for personal devices with strict limits; a paid developer team is better for CI).
  • A team id (xcodeOrgId capability) and signing identity (xcodeSigningId, usually iPhone Developer).
  • A provisioning profile that includes the device, generally generated automatically when you open the WDA project in Xcode once and let it manage signing, or by supplying updatedWDABundleId.
  • The iPhone in Developer Mode (Settings, Privacy & Security), trusted by your Mac and connected by USB (or wirelessly on newer setups).

Typical symptoms of a signing problem: the session hangs while "building WebDriverAgent", or the log reports a provisioning or code-sign failure. These are fixed in Xcode, not in your test.

Choosing a device name correctly

Simulator names change between Xcode versions ("iPhone 15" disappears and "iPhone 16" arrives). Teams therefore resolve the device from a listing instead of hard coding. The stand-in below parses a sample text shaped like xcrun simctl list devices available output and picks the newest iPhone runtime. It is a stand-in that shows the logic; real output on your Mac may differ slightly.

JS Stand-in: pick a simulator from a listing

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Checking a real-device plan

Before a real-device run, a checklist avoids wasted hours. The stand-in turns the signing requirements into a validator you can adapt for your own capability object.

JS Stand-in: real device capability checklist

Press Run (or Ctrl + Enter) to see the console output here.

No output.

No Mac? Your options

  • A Mac build agent (a Mac mini in a rack or a hosted Mac service) running your Appium server, with tests triggered from anywhere.
  • A cloud device farm, which provides Macs and real iPhones behind a remote Appium endpoint, discussed later in the course.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the XCUITest driver build and run on the iOS target?

    WebDriverAgent is the XCUITest-based helper that exposes automation commands over HTTP.
  2. 2. Which command lists available simulators?

    simctl is Apple's simulator control tool; list devices available shows what can be booted.
  3. 3. Why can't you install a real-device IPA onto a simulator?

    Device apps are compiled for the iPhone CPU and signed; simulator apps are built for the simulator.
  4. 4. A real-device session hangs while building WebDriverAgent with a provisioning error. Where is the fix?

    WDA must be signed with a valid identity; fix signing in Xcode and the xcodeOrgId and xcodeSigningId capabilities.

Summary

  • iOS automation needs a Mac, Xcode, command line tools and the xcuitest driver.
  • xcrun simctl manages simulators; each has a name, version and UDID.
  • The driver builds WebDriverAgent, which runs a small HTTP server on the target.
  • Real devices need Developer Mode, trust, a team id, a signing identity and a signed IPA.
  • Resolve simulator names from listings instead of hard coding them.

Next: Appium Inspector and Environment Checks