Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Android and iOS Specifics

iOS Automation with XCUITest and WebDriverAgent

Automate iOS apps with Appium's XCUITest driver: Mac requirements, WebDriverAgent, code signing, predicate and class chain locators, and simulators.

iOS automation works differently from Android in one important way: Apple controls the toolchain. To automate an iPhone or iPad app, Appium relies on Apple's own XCUITest framework, and that framework only runs on a Mac with Xcode installed. There is no supported way to run iOS tests from Windows or Linux, except by renting Macs or real devices from a cloud farm (covered in the chapter on device clouds).

This lesson explains how the XCUITest driver works, what WebDriverAgent is and why it needs code signing for real devices, which capabilities you set, and how the iOS-only locator strategies are written.

Appium, Xcode and iOS simulators cannot run on this site, so the Appium snippets are read-only and the runnable code is a stand-in that parses and builds the same kinds of strings.

How the pieces fit

flowchart LR
    T["Test script"] --> S["Appium server"]
    S --> D["XCUITest driver"]
    D --> X["xcodebuild"]
    X --> W["WebDriverAgent runner app"]
    W --> A["App under test"]

Your script talks to Appium; the driver builds and starts WebDriverAgent, which controls the app through XCUITest.

WebDriverAgent (WDA) is a small XCUITest-based app that acts as a WebDriver server inside the device or simulator. Appium's driver launches it with xcodebuild, then forwards your commands to it. When a session starts you will see Xcode build WDA first. That is why the first session on a machine is slow, and why a broken Xcode installation breaks everything.

Preparing a Mac

  1. Install Xcode from the App Store and open it once to accept the license and install components.
  2. Install the command line tools: xcode-select --install.
  3. Install Appium and the driver:
Terminal
npm install -g appium
appium driver install xcuitest
appium driver doctor xcuitest
  1. For simulators, create or pick one in Xcode (Window, Devices and Simulators) or list them with xcrun simctl list devices.

Simulators need no signing at all. Real devices need extra work, described next.

Real devices and code signing

Apple only lets signed apps run on physical devices, and WebDriverAgent is an app. You must give the driver a team and signing identity:

Python
from appium import webdriver
from appium.options.ios import XCUITestOptions

options = XCUITestOptions()
options.platform_name = "iOS"
options.platform_version = "18.2"
options.device_name = "iPhone 16"
options.udid = "00008110-001A2B3C4D5E6F78"
options.app = "/path/to/Shop.app"            # a simulator build is a .app folder; a device build is an .ipa
options.set_capability("appium:xcodeOrgId", "ABCDE12345")
options.set_capability("appium:xcodeSigningId", "iPhone Developer")
options.set_capability("appium:updatedWDABundleId", "com.example.wda")

driver = webdriver.Remote("http://127.0.0.1:4723", options=options)

The team ID comes from your Apple developer account (a free account works, with limits). updatedWDABundleId gives WDA a unique bundle ID so it does not clash with other developers' copies. On the device you must also trust the developer certificate and enable Developer Mode.

Capability Meaning
appium:automationName XCUITest (set automatically by the options class)
appium:platformVersion iOS version of the simulator or device
appium:udid Exact device or simulator ID; required for real devices
appium:app Path or URL to a .app (simulator) or .ipa (device)
appium:bundleId Start an already installed app by bundle ID
appium:useNewWDA Reinstall WDA each session (slower, useful after crashes)
appium:wdaLocalPort Fixed local port; vital when running devices in parallel
appium:autoAcceptAlerts Tap "Allow" on system dialogs automatically

iOS locator strategies

Accessibility ID still comes first; on iOS it maps to the view's accessibilityIdentifier. Two strategies are specific to iOS and much faster than XPath.

Predicate strings use Apple's NSPredicate syntax:

Python
from appium.webdriver.common.appiumby import AppiumBy

driver.find_element(AppiumBy.IOS_PREDICATE,
    'type == "XCUIElementTypeButton" AND label BEGINSWITH "Sign"')
driver.find_element(AppiumBy.IOS_PREDICATE, 'name CONTAINS[c] "cart"')

Class chains walk the hierarchy with a compact path, with optional predicates in backticks:

Python
driver.find_element(AppiumBy.IOS_CLASS_CHAIN,
    '**/XCUIElementTypeCell[`label CONTAINS "Shoes"`]/XCUIElementTypeButton[1]')

Element types are named XCUIElementTypeButton, XCUIElementTypeTextField, XCUIElementTypeStaticText, XCUIElementTypeCell, and so on. Attributes you can match are name, label, value, type, visible, enabled and accessible.

Stand-in: a predicate matcher

A real predicate runs inside WebDriverAgent. This tiny stand-in understands only ==, BEGINSWITH and CONTAINS[c] joined by AND, over a fake screen, to show how matching on label and type narrows the result.

Python Predicate matcher (stand-in)

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Simulator versus real device

A simulator runs a compiled-for-Mac build of your app, starts quickly, can be reset with one command and supports features such as biometric enrolment. A real device exposes true performance, camera, push notifications and hardware behavior. Most teams run the bulk of their suite on simulators in CI and a smaller smoke set on real devices.

Useful simulator commands outside Appium:

Terminal
xcrun simctl list devices available
xcrun simctl boot "iPhone 16"
xcrun simctl install booted Shop.app
xcrun simctl privacy booted grant photos com.example.shop
xcrun simctl erase all

Common problems

  • "xcodebuild failed with code 65": usually a signing problem; open the WebDriverAgent.xcodeproj under the driver's folder in Xcode, select your team once and build the WebDriverAgentRunner scheme to see the real error.
  • Session starts but the app is blank: the app was built for a different architecture than the target. Build for the simulator for simulator runs.
  • Parallel devices fight over one port: set a distinct appium:wdaLocalPort (and appium:derivedDataPath when needed) per device.
  • Slow lookups: XPath on iOS walks a huge tree. Switch to class chain or predicates.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is WebDriverAgent?

    The XCUITest driver builds and launches WDA, then forwards commands to it.
  2. 2. Which environment is required to run iOS tests locally?

    XCUITest only runs under macOS with Xcode, so Windows and Linux teams use Macs or cloud devices.
  3. 3. Which locator strategies are specific to iOS and faster than XPath?

    iOS predicate and class chain strategies are evaluated natively by WebDriverAgent.
  4. 4. Why does a real device need xcodeOrgId and updatedWDABundleId?

    Apple only runs signed apps on physical devices, so WDA needs your signing team and its own bundle ID.

Summary

  • iOS automation uses Apple's XCUITest through the Appium XCUITest driver and needs a Mac with Xcode.
  • WebDriverAgent is built and launched for every new session; first runs are slow.
  • Real devices need signing capabilities, a trusted certificate and Developer Mode; simulators need none of that.
  • Prefer accessibility ID, then predicate strings and class chains; avoid broad XPath.
  • Use a unique wdaLocalPort per device when running in parallel.

Next: Hybrid Apps and WebViews: Switching Contexts