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:

  • The device needs to be trusted:

    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

  • 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.