Skip to content

Run Preinstalled WebDriverAgentRunner

The XCUITest driver can be configured to launch an already-installed WebDriverAgentRunner-Runner application (WDA) on a real device. This allows you to start a session without the xcodebuild command execution, improving the session startup performance.

Warning

This method currently does not work natively for iOS 17/tvOS 17 due to platform changes. Please use the default xcodebuild approach or 3rd party tools such as pymobiledevice3.

Capabilities

Install WebDriverAgent

Using Xcode

Running a test for the WDA package in Xcode is the easiest way to prepare the device environment:

  1. Open WebDriverAgent project in Xcode
    • You can run appium driver run xcuitest open-wda if using XCUITest driver 4.13 or newer
  2. Select the WebDriverAgentRunner scheme
  3. Select the scheme as Product -> Scheme -> WebDriverAgentRunner (or WebDriverAgentRunner_tvOS for tvOS)
  4. Select your device in Product -> Destination
  5. Select Product -> Test to build and install the WDA app

If using a real device, you may need to change your bundle ID. Please check the Full Manual Provisioning Profile setup for details.

Using 3rd Party Tools

Some 3rd party tools such as pymobiledevice3, ios-deploy, go-ios and tidevice can install the WebDriverAgent package.

The WDA app package (WebDriverAgentRunner-Runner.app) can be generated in the derivedDataPath directory, as explained in Manual Configuration for a Generic Device. The app can then be installed without xcodebuild using the 3rd party tools.

Launch the Session

After installing the WebDriverAgentRunner-Runner application, you can start the Appium server and launch an XCUITest driver session with the specified capabilities:

appium

# Ruby
capabilities: {
  "platformName": "ios",
  "appium:automationName": "xcuitest",
  "appium:udid": "<udid>",
  "appium:usePreinstalledWDA": true,
  "appium:updatedWDABundleId": "com.appium.WebDriverAgentRunner"
}
@core = Appium::Core.for capabilities: capabilities
driver = @core.start_driver
# do something
driver.quit

If the <udid> device has a WebDriverAgent package with com.appium.WebDriverAgentRunner.xctrunner bundle ID, the session will launch the WebDriverAgent process without xcodebuild.

Note

Please ensure that the WDA application is launchable before starting an XCUITest driver session. For example, check whether the provisioning profile is trusted.

Set appium:prebuiltWDAPath

If the appium:prebuiltWDAPath capability is provided with a properly signed WebDriverAgentRunner-Runner.app test bundle, the XCUITest driver will install the application and launch it every test session. Test bundles cannot be versioned using CFBundleVersion as vanilla applications do, which is why it is necessary to (re)install them for every test session.

Usually you can find the WDA application bundle at the below location if you use Xcode to build it.

~/Library/Developer/Xcode/DerivedData/WebDriverAgent-<random string>/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app

You can then set your Appium capabilities as follows:

# Ruby
capabilities: {
  "platformName": "ios",
  "appium:automationName": "xcuitest",
  "appium:udid": "<udid>",
  "appium:usePreinstalledWDA": true,
  "appium:prebuiltWDAPath": "/path/to/Library/Developer/Xcode/DerivedData/WebDriverAgent-<random string>/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app"
}
@core = Appium::Core.for capabilities: capabilities
driver = @core.start_driver
# do something
driver.quit

Note

As of iOS 17, the testmanagerd service name has changed from com.apple.testmanagerd to com.apple.dt.testmanagerd.runner. It causes an unexpected WDA process crash with embedded XCTest frameworks while running a single WebDriverAgent package on various OS environments without xcodebuild.

Since WDA v5.10.0, the module can refer to the device's local XCTest frameworks. It lets the Appium/WebDriverAgent package use proper dependencies for the device with a single prebuilt WebDriverAgent package. To set this up, you should remove the package internal frameworks from WebDriverAgentRunner-Runner.app with rm -rf WebDriverAgentRunner-Runner.app/Frameworks/XC*.framework. The WDA package itself is available from https://github.com/appium/WebDriverAgent.