Overview

The XCUITest driver is an Appium driver intended for black-box automated testing of several Apple ecosystem platforms.

Target Platforms

The driver supports the following Apple platforms as automation targets:

Platform	Simulators	Real devices
iOS
iPadOS
tvOS
watchOS
visionOS
macOS	N/A	1
Safari (mobile)	2	2
Safari (desktop)	3	3

A detailed breakdown of the supported platform versions can be found in the Installation page.

Contexts

The following application contexts are supported for automation:

• Native applications
• Webviews based on Safari
• Webviews based on Chrome (since Chrome 115 & iOS 16.4)
• Hybrid applications

Note that only debuggable webviews are supported.

Technologies Used

Under the hood, the driver combines several different technologies to achieve its functionality:

• Native testing
  • Based on Apple's XCTest framework
  • Provided by the appium-webdriveragent library (a fork of the original implementation by Facebook)
  • Uses the W3C WebDriver protocol with several platform-specific extensions
• Webview testing
  • Based on Safari's WebKit Remote Debugger Protocol (not officially documented)
  • Provided by the appium-remote-debugger library
  • Interaction with webpages is based on Selenium atoms
  • Can only use the legacy JSONWP protocol due to the atoms
  • Better, WebDriver protocol-compatible support is also provided by the Appium Safari driver
• Simulator communication
  • Based on the xcrun simctl and other xcrun command line utility calls
  • Provided by the appium-ios-simulator library
• Real device communication
  • Legacy approach (to be eventually deprecated)
    • Based on re-implemented libimobiledevice system calls
    • Provided by the appium-ios-device library
  • Modern approach (iOS/tvOS 18+ only)
    • Based on remote XPC services
    • Provided by the appium-ios-remotexpc library

End-to-End Architecture

The diagram below is intentionally the simplest end-to-end example. Cloud service providers, device farms, network gateways, and sophisticated local setups may insert additional layers between the client library and the automation host.

flowchart TD
  subgraph ClientSide["Test Client"]
    T["Test Code"]
    CL["Appium Client Library<br/>(Java / Python / JS / Ruby / C#)"]
  end

  subgraph ServerHost["Automation Host"]
    AS["Appium Server"]
    XD["XCUITest Driver<br/>(appium-xcuitest-driver)"]
    HWS["WDA Management (Simulator)"]
    HWR["WDA Management (Real Device)"]
  end

  subgraph SimulatorTarget["Simulator"]
    WDAS["WebDriverAgent Server"]
    XCTS["XCTest Runtime"]
    AUTS["Application Under Test"]
  end

  subgraph RealDeviceTarget["Real Device"]
    WDAR["WebDriverAgent Server"]
    XCTR["XCTest Runtime"]
    AUTR["Application Under Test"]
  end

  T --> CL
  CL -->|"W3C WebDriver over HTTP"| AS
  AS -->|"Routes iOS commands"| XD
  XD -->|"Starts/monitors WDA, proxies commands"| HWS
  XD -->|"Starts/monitors WDA, proxies commands"| HWR
  HWS -->|"xcrun simctl + CoreSimulator tooling"| WDAS
  HWR -->|"usbmux / Remote XPC / xcrun devicectl"| WDAR
  WDAS -->|"XCTest automation APIs"| XCTS
  WDAR -->|"XCTest automation APIs"| XCTR
  XCTS -->|"UI interactions + assertions"| AUTS
  XCTR -->|"UI interactions + assertions"| AUTR

  AUTS -->|"UI state/result"| XCTS
  AUTR -->|"UI state/result"| XCTR
  XCTS --> WDAS
  XCTR --> WDAR
  WDAS --> XD
  WDAR --> XD
  XD --> AS
  AS --> CL
  CL --> T

Command Flow at Runtime

1. The test sends a command via a client library (for example findElement, click, or executeScript).
2. The Appium server forwards the command to this driver based on the active session.
3. The XCUITest driver translates/proxies the command to WebDriverAgent (WDA), and manages WDA lifecycle when needed.
4. WDA uses XCTest internals to drive the app UI on simulator or real device.
5. The result comes back through the same chain to the client.

Transport and Responsibilities

• Client library to Appium server: W3C WebDriver HTTP protocol.
• Appium server to this driver: in-process driver command dispatch.
• This driver to WDA: HTTP proxying to the WDA REST API.
• WDA to XCTest: native Apple automation stack.
• This driver to real devices: host-device communication uses usbmux-based transport, Remote XPC tunneling, and xcrun devicectl depending on iOS/tvOS version and environment setup.
• This driver to simulators: host-simulator communication uses xcrun simctl (plus related CoreSimulator tooling).

---

1. Supported by the Appium Mac2 driver ↩

2. Also supported by the Appium Safari driver ↩↩

3. Supported by the Appium Safari driver ↩↩