The XCUITest Driver for iOS

Appium's primary support for automating iOS apps is via the XCUITest driver. (New to Appium? Read our introduction to Appium drivers). This driver leverages Apple's XCUITest libraries under the hood in order to facilitate automation of your app . This access to XCUITest is mediated by the WebDriverAgent server. 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 example).

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

If you are migrating to the XCUITest driver from Appium's old UIAutomation-based driver, you may wish to consult this migration guide.

Usage

The way to start a session using the XCUITest driver is to include the automationName capability in your new session request, with the value XCUITest. Of course, you must also include appropriate platformName, platformVersion, deviceName, and app capabilities, at a minimum.

Capabilities

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 app capability empty and instead set the browserName capability to Safari.

Commands

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.

Basic Setup

(We recommend the use of Homebrew for installing system dependencies)

1. Ensure that you have Appium's general dependencies (e.g., Node & NPM) installed and configured.

2. 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 or .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:

• app or bundleId - specifies the application (local path or url referencing your signed .ipa file) , 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 auto if 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:

$HOME/Library/Logs/CoreSimulator/*
$HOME/Library/Developer/Xcode/DerivedData/*