Configure iOS Drivers

What is the XCUITest Driver?

The XCUITest driver is the Appium driver for automating iOS, iPadOS, and tvOS applications. It uses Apple’s XCUITest framework under the hood via WebDriverAgent (WDA), a WebDriver server that runs on the device alongside your app.

Before you can run iOS UI tests through Appium, the XCUITest driver and its embedded WebDriverAgent project must be properly configured and signed.

Prerequisites

Appium testing Xcode ides

Ensure you have:

Appium installed with the xcuitest driver (appium driver install xcuitest)
Xcode installed with Command Line Tools configured
An Apple ID signed into Xcode (required for code signing)

Before configuring the driver, you need an Apple ID signed into Xcode:

Launch Xcode
Click Xcode in the menu bar, then click Settings (or press Cmd + ,)
Select the Accounts tab
If no accounts are listed, click the + button to add one
Select Apple ID and sign in with your credentials

You must use an Apple ID to build and sign projects. Other account types (Xcode Server, Bitbucket, etc.) cannot be used for code signing.

Open the WebDriverAgent Project

Since Appium 2, driver sources are installed under ~/.appium by default.

Using the Appium CLI (Recommended)

The XCUITest driver (v4.13.0+) includes a convenience command to open the WDA project directly in Xcode:

appium driver run xcuitest open-wda

Alternatively, navigate to the project directory and open it manually:

cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent

xed WebDriverAgent.xcodeproj

Xcode should open the project with the Project Explorer visible, showing the WebDriverAgent folder structure including WebDriverAgentLib, WebDriverAgentRunner, and other sub-folders.

Configure Code Signing

You need to configure signing for both the WebDriverAgentLib and WebDriverAgentRunner targets.

Configure WebDriverAgentLib

In the Project Explorer, click on WebDriverAgentLib under TARGETS
Click on the Signing & Capabilities tab
Check Automatically manage signing
Select your Team from the dropdown (your Apple ID / Personal Team)
Modify the Bundle Identifier to make it unique (see below)

Configure WebDriverAgentRunner

In the Project Explorer, click on WebDriverAgentRunner under TARGETS
Click on the Signing & Capabilities tab
Check Automatically manage signing
Select your Team from the dropdown
Modify the Bundle Identifier to make it unique (see below)

Update Bundle Identifiers

The default bundle identifiers will fail to register because they are already taken. You need to append a unique suffix to each:

Target	Default	Updated
`WebDriverAgentLib`	`com.facebook.WebDriverAgentLib`	`com.facebook.WebDriverAgentLib<YourSuffix>`
`WebDriverAgentRunner`	`com.facebook.WebDriverAgentRunner`	`com.facebook.WebDriverAgentRunner<YourSuffix>`

Replace <YourSuffix> with something unique and meaningful (e.g., your name or initials).

If you see a “Failed to register bundle identifier” error, it means the bundle ID is already taken. Change it to something unique and click Try Again.

Capability-Based Signing (Alternative)

Instead of manually configuring signing in Xcode, you can pass signing credentials via Appium capabilities:

{
  "appium:xcodeOrgId": "<YOUR_TEAM_ID>",
  "appium:xcodeSigningId": "iPhone Developer"
}

Build the Project

After configuring signing for both targets:

Click the Play button in Xcode to build the project
If successful, you will see a Build Succeeded message
Click the Stop button to stop the build

A successful build confirms that code signing is properly configured and the WebDriverAgent can be deployed to your target device.

Run the Verification Test

The XCUITest driver includes built-in tests to verify that your device connection is working correctly.

Get Your Device UDID

Make sure you have a running Simulator or a physical device connected to your Mac.

For Simulators:

xcrun simctl list devices booted

For Physical Devices:

ios-deploy -c

Copy the device UDID from the output.

Run the Test

Navigate to the WebDriverAgent directory and run the test:

cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent

xcodebuild -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination 'id=<device-udid>' \
  test

Replace <device-udid> with the UDID you copied in the previous step.

Your terminal will fill with build output. When you see Testing started, the connection is working correctly. Press Ctrl + C to stop the tests.

If the build fails with an error mentioning “Provision”, there is an issue with your provisioning profile. Check the error message for specific arguments to add to the command.

Real Device Requirements

When testing on physical iOS devices, note these additional requirements:

iOS/iPadOS 16+: You must enable Developer Mode on the device (Settings > Privacy & Security > Developer Mode)
UI Automation: Enable Settings > Developer > Enable UI Automation
Trust: When deploying WDA for the first time, you may need to trust the developer certificate on the device (Settings > General > VPN & Device Management)

Good to Know

Useful Aliases

Add these aliases to your ~/.zshrc to quickly check connected devices:

# List running simulators
alias active-sims="xcrun simctl list devices booted"

# List connected physical devices
alias connected-devices="ios-deploy -c"

Updating the XCUITest Driver

When you update the XCUITest driver, the WebDriverAgent project is also updated. You may need to reconfigure signing after an update:

appium driver update xcuitest

Troubleshooting

”Failed to register bundle identifier”

The default WDA bundle identifiers are already taken. Update them with a unique suffix as described in the Update Bundle Identifiers section.

Provisioning Profile Errors

If xcodebuild fails with provisioning-related errors:

Open the WDA project in Xcode (appium driver run xcuitest open-wda)
Verify both targets have Automatically manage signing enabled
Confirm your Team is selected for both targets
Ensure bundle identifiers are unique

”xcodebuild: error: … requires Xcode”

Ensure the Xcode Command Line Tools path is set correctly:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Device Not Detected

For physical devices, ensure:

The device is connected via USB and trusted
ios-deploy is installed for device detection
libimobiledevice is installed for device communication

Session Creation Errors

Run driver diagnostics to identify environment issues:

appium driver doctor xcuitest

`ECONNREFUSED 127.0.0.1:8100` (WebDriverAgent failure)

This means WebDriverAgent failed to start on the device or simulator. The error typically appears as:

Could not proxy command to the remote server.
Original error: connect ECONNREFUSED 127.0.0.1:8100

Add retry capabilities to give WDA more time to start:

caps = {
    "appium:wdaStartupRetries": 4,
    "appium:iosInstallPause": 8000,
    "appium:wdaStartupRetryInterval": 20000,
}

If the issue persists, manually remove WDA so Appium can reinstall it on the next session:

# For simulators — uninstall the WDA bundle
xcrun simctl uninstall booted com.facebook.WebDriverAgentRunner.xctrunner

# For real devices — go to Settings > General > VPN & Device Management
# and remove the WebDriverAgent profile

Appium will automatically reinstall WDA when you start the next test session.

Slow iOS Test Execution

If tests run noticeably slower than manual interactions, the XCUITest driver may be waiting for the app to become idle between actions. Disable the idle wait:

caps = {
    "appium:waitForIdleTimeout": 0,
}

This tells the XCUITest driver to skip waiting for the app to reach an idle state before executing the next command. This significantly improves speed for apps with continuous animations or background activity.