Skip to content

Device Preparation

Before using the XCUITest driver with any device (either simulator or real device), additional configuration is required on the device itself.

Automatic Adjustments

The driver automatically adjusts certain device settings. Currently this only applies to keyboard-related preferences. Some of these preferences can still be adjusted manually via the Settings API.

  • Settings -> General -> Keyboard -> Auto-Correction is turned OFF
  • Settings -> General -> Keyboard -> Predictive Text is turned OFF
  • The keyboard tutorial is marked as complete
  • (Simulator Only) Software keyboard is turned ON

Accessibility Settings

Certain accessibility settings may affect the elements shown in the application page source.

  • Ensure zoom is turned off in order to avoid miscalculation of element coordinates:

    Settings -> Accessibility -> Zoom -> Turn Zoom OFF

  • Other settings may be adjusted depending on your testing requirements:

    Settings -> Accessibility -> Read & Speak -> Speak Selection

Real Devices

In order to communicate with both simulators and real devices, the XCUITest driver must install the WebDriverAgentRunner-Runner (WDA) application on the device. Unlike simulators, real devices will not allow this by default, and have several security restrictions that need to be manually lifted beforehand.

Trusting the Device

The device needs to be trusted in order to appear as a run destination in Xcode.

Wired Devices

  1. On your macOS computer, open Xcode
  2. Physically connect the device to the computer
  3. On the device, a Trust This Computer popup should appear - accept it

Wireless tvOS Devices

  1. On your macOS computer, open Xcode
  2. Ensure the Apple TV is on the same network as the macOS host (no firewall blocking)
  3. On the Apple TV, enable discovery mode in Settings -> Remotes and Devices -> Remote App and Device
  4. In Xcode, open Window -> Devices and Simulators - the Apple TV should appear
  5. Click Pair, enter the PIN that appears on the Apple TV, then click Connect

Required Settings

  • The device must have Developer Mode enabled (iOS/iPadOS 16+ only):

    Settings -> Privacy & Security -> Developer Mode -> Turn Developer Mode ON

    You can also use the devmodectl streaming CLI on macOS 13+ and install development signed apps to enable this mode.

  • UI Automation must be enabled:

    Settings -> Developer -> Turn Enable UI Automation ON

  • For webview testing, Safari automation-related settings must be enabled:

    Settings -> Apps -> Safari -> Advanced -> Turn Web Inspector ON

    Settings -> Apps -> Safari -> Advanced -> Turn Remote Automation ON

Provisioning Profile

In addition to all of the above device configuration, the WDA application must have a valid provisioning profile in order for it to be installable on your target device. Refer to the Provisioning Profile guide for more details on how to configure this.