The XCUITest Driver for iOS
Appium's primary support for automating iOS apps is via the
(New to Appium? Read our introduction to Appium drivers). This driver
libraries under the hood in order to facilitate automation of your app . This
access to XCUITest is mediated by the
WebDriverAgent (also referred to as "WDA") is a project managed by Facebook, to
which the Appium core team contributes heavily. WDA is a WebDriver-compatible
server that runs in the context of an iOS simulator or device and exposes the
XCUITest API. Appium's XCUITest driver manages WDA as a subprocess opaque to
the Appium user, proxies commands to/from WDA, and provides a host of
additional functionality (like simulator management and other methods, for
Development of the XCUITest driver happens at the appium-xcuitest-driver repo.
Requirements and Support
In addition to Appium's general requirements:
- Apple's XCUITest library is only available on iOS simulators and devices that are running iOS 9.3 or higher.
- A Mac computer with macOS 10.11 or 10.12 is required.
- Xcode 7 or higher is required.
- The XCUITest driver was available in Appium starting with Appium 1.6.
- For correct functioning of the driver, additional system libraries are required (see the Setup sections below).
Migrating from the UIAutomation Driver
The way to start a session using the XCUITest driver is to include the
automationName capability in your new session request, with
XCUITest. Of course, you must also include appropriate
app capabilities, at
The XCUITest driver supports a number of standard Appium capabilities, but has an additional set of capabilities that modulate the behavior of the driver. These can be found currently at the appium-xcuitest-driver README.
To automate Safari instead of your own application, leave the
empty and instead set the
browserName capability to
To see the various commands Appium supports, and specifically for information on how the commands map to behaviors for the XCUITest driver, see the API Reference.
(We recommend the use of Homebrew for installing system dependencies)
- Ensure that you have Appium's general dependencies (e.g., Node & NPM) installed and configured.
Install the Carthage dependency manager:
bash brew install carthage
If you don't need to automate real devices, you're done! To automate an app on
the simulator, the
app capability should be set to an absolute path or url
pointing to your
.app.zip file, built for the sim.
Real Device Setup
Automating a real device with XCUITest is considerably more complicated, due to Apple's restrictions around running apps on real devices. Please refer to the XCUITest real device setup doc for instructions.
Once set up, running a session on a real device is achieved by using the following desired capabilities:
bundleId- specifies the application (local path or url referencing your signed
.ipafile) , or, if it is already installed, simply the bundle identifier of the app so that Appium can launch it.
udid- the specific id of the device to test on. This can also be set to
autoif there is only a single device, in which case Appium will determine the device id and use it.
Files generated by test runs
Testing on iOS generates files that can sometimes get large. These include logs, temporary files, and derived data from Xcode runs. Generally the following locations are where they are found, should they need to be deleted: