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 | |
| Safari (mobile) | ||
| Safari (desktop) |
A detailed breakdown of the supported platform versions can be found in the System Requirements 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-webdriveragentlibrary (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-debuggerlibrary - Interaction with webpages relies on Selenium-style "atoms", which are based on the original Selenium atoms
- Uses the W3C WebDriver protocol
- Alternative support for Safari automation is also provided by the Appium Safari driver
- Simulator communication
- Based on the
xcrun simctland otherxcruncommand line utility calls - Provided by the
appium-ios-simulatorlibrary
- Based on the
- Real device communication
- Provided by the
appium-ios-remotexpclibrary - Preferred: remote XPC services over a tunnel (iOS/tvOS 18+)
- Temporary fallback when no tunnel is running: the classic lockdown services over
usbmux. It supports a limited set of features (see the feature availability table) and is expected to stop working once Apple removes these services. This is also the only mode available for devices running iOS/tvOS < 18
- Provided by the
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 device 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¶
- The test sends a command via a client library (for example
findElement,click, orexecuteScript). - The Appium server forwards the command to this driver based on the active session.
- The XCUITest driver translates/proxies the command to WebDriverAgent (WDA), and manages WDA lifecycle when needed.
- WDA uses XCTest internals to drive the app UI on simulator or real device.
- 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, andxcrun devicectldepending on iOS/tvOS version and environment setup. - This driver to simulators: host-simulator communication uses
xcrun simctl(plus related CoreSimulator tooling).
-
Only the Simulator is supported - see watchOS Automation ↩
-
Supported by the Appium Mac2 driver ↩
-
Also supported by the Appium Safari driver ↩↩
-
Supported by the Appium Safari driver ↩↩