Skip to content

Run Prebuilt WebDriverAgentRunner

The XCUITest driver runs xcodebuild to build and install the WebDriverAgentRunner (WDA) app on the target device. You can manually run a modified version of this command in order to prebuild the WDA.

How xcodebuild Works

By default, xcodebuild is run with two commands: build-for-testing and test-without-building. build-for-testing builds a test bundle package, whereas test-without-building actually runs it.

For instance, XCUITest driver issues an xcodebuild command like so:

xcodebuild build-for-testing test-without-building \
  -project WebDriverAgent.xcodeproj \
  -derivedDataPath wda_build \
  -scheme WebDriverAgentRunner \
  -destination "platform=iOS Simulator,name=iPhone 14 Pro" \
  CODE_SIGNING_ALLOWED=NO

This translates to xcodebuild building WebDriverAgent.xcodeproj and running the resulting package on the specified device.

The command can be split into build-for-testing and test-without-building parts as follows:

xcodebuild build-for-testing \
  -project WebDriverAgent.xcodeproj \
  -derivedDataPath wda_build \
  -scheme WebDriverAgentRunner \
  -destination "platform=iOS Simulator,name=iPhone 14 Pro" \
  CODE_SIGNING_ALLOWED=NO

xcodebuild test-without-building \
  -xctestrun wda_build/Build/Products/WebDriverAgentRunner_iphonesimulator16.2-arm64.xctestrun \
  -destination "platform=iOS Simulator,name=iPhone 14 Pro"

  • The build-for-testing command generates two files: an .app package and an .xctestrun file, e.g.:

    wda_build/Build/Products/Debug-iphonesimulator/WebDriverAgentRunner-Runner.app
wda_build/Build/Products/WebDriverAgentRunner_iphonesimulator16.2-arm64.xctestrun

    The .xctestrun file name depends on the -destination preference. The file contains metadata about the package (the DependentProductPaths key).

  • The test-without-building command starts the WDA application for testing by referencing the provided .xctestrun file. Once this is done, http://localhost:8100 will be able to receive commands for the target device.

Capabilities for Prebuilt WDA

The XCUITest driver provides two capabilities that allow skipping the build-for-testing command, and executing only the test-without-building command: appium:useXctestrunFile and appium:bootstrapPath (see Capabilities).

Note

These capabilities expect that the WDA files are already prebuild, so make sure to first run xcodebuild to create the files.

This method can be used on both real devices and simulators, but real devices requires proper signing as described in Run Preinstalled WebDriverAgentRunner. We recommend using this method for real devices.

The capabilities can be used as follows:

{
  "platformName": "ios",
  "appium:automationName": "xcuitest",
  "appium:platformVersion": "15.5",
  "appium:deviceName": "iPhone 12",
  "appium:useXctestrunFile": true,
  "appium:bootstrapPath": "/path/to/wda_build/Build/Products"
}

Not all combinations have been tested, but the target device can probably be anything.

The same thing can be achieved with the appium:derivedDataPath and appium:usePrebuiltWDA capabilities, but this may fail if xcodebuild cannot find or handle the .xctestrun file properly. The stability depends on Xcode.

Download Prebuilt WDA

The Appium WebDriverAgent GitHub page provides downloads for WebDriverAgent packages for real devices. They do not have embedded XCTest frameworks.

The Release and Building WebDriverAgent workflows may help with validating the build script.