Mobile Automation Docs

Appearance

WebDriverAgent Setup ​

Introduction ​

WebDriverAgent (WDA) is an essential component for automating iOS devices with Appium. It is a WebDriver server implementation for iOS that is used to remotely control iOS devices. It is developed and used at Facebook for end-to-end testing and has been open-sourced.

In our setup, WebDriverAgent acts as the bridge between the Appium server and your iOS device. Appium translates the WebDriver commands from your test script into instructions that the XCUITest framework can understand, and WebDriverAgent executes these instructions on the device.

When you installed the XCUITest driver, a compatible version of WebDriverAgent was automatically downloaded.

Prerequisites ​

Before proceeding, it is crucial to ensure that you have successfully completed all the previous steps in the iOS automation section. The configurations for macOS and Xcode, your Apple ID, and the physical iOS Device are all necessary for this stage.

This guide follows the manual setup process using a free Apple ID, as detailed in the Appium documentation.

1: Open WebDriverAgent ​

The WebDriverAgent project is located within the appium-xcuitest-driver installation directory. The easiest way to find it is by using the find command in your terminal.

sh
find ~/.appium -name "WebDriverAgent.xcodeproj"

The command will output the full path to the Xcode project. Copy this path, and open the project in Xcode.

sh
# Example of opening the project from the terminal
open /Users/your_user/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj

After opening the WebDriverAgent in XCode, the screen should look as follows:

WebdriverAgent

2: Scheme and Destination ​

  1. Connect the device (iPhone) to the developer computer as described here.
  2. In Xcode, select the WebDriverAgent project in the left-hand navigator.
  3. Click on menu Product-> Scheme -> WebDriverAgentRunner.
  4. Click on menu Product-> Destination -> iPhone.

3: Signing for AgentLib ​

  1. Select the WebDriverAgentLib target from the targets list.
  2. Go to the Signing & Capabilities tab.
  3. Check the Automatically manage signing box.
  4. Select your Apple ID from the Team dropdown menu.
  5. Change Bundle Identifier from com.facebook... to another different text, like com.automatedtests...

4: Signing for AgentRunner ​

  1. Now, select the WebDriverAgentRunner target.
  2. Go to the Signing & Capabilities tab.
  3. Check the Automatically manage signing box.
  4. Select your Apple ID from the Team dropdown menu.
  5. Change Bundle Identifier from com.facebook... to another different text, like com.automatedtests...

After configuring the Signing & Capabilities tab, the screen should look as follows:

Signin

5: Build and Test ​

Now it's time to build WebDriverAgent and install it on your connected iOS device.

From the menu bar, select Product > Test.

This will start the build process. It may take a few minutes.

Trusting the Certificate ​

If this is the first time you are using your Apple ID for development on this device, the build will fail, and you will see a security error.

Failed

To resolve this, you need to trust the developer certificate on your iPhone:

  1. Open the Settings app on your iPhone.

  2. Go to General > VPN & Device Management.

  3. Under Developer App, you will see your Apple ID email address. Tap on it.

    Allow

  4. Tap the Trust button.

    Trust

Step 5: Verify the Installation ​

After trusting the certificate, go back to Xcode and run the test again (Product > Test).

This time, the build should succeed. WebDriverAgent will be installed and launched on your device, and the Xcode console will show logs from the WDA server, indicating that it is running and ready to receive commands.

The iPhone screen will shows the message "Automation Running".

Once you see the server running, you can stop the test by clicking the stop button in Xcode. The WebDriverAgent app will remain installed on your device for future automation sessions.

Limitations of a Free Apple ID ​

Using a free Apple ID for development and testing on your own devices is a great way to get started with iOS automation. However, it's important to be aware of the limitations that come with a free account compared to a paid Apple Developer account:

  • 7-Day Provisioning Profile: The provisioning profile generated with a free Apple ID is only valid for 7 days. After this period, the WebDriverAgent app on your device will no longer launch, and you will need to repeat the build and test process in Xcode to reinstall it.
  • Limited Number of Devices: You can only register a limited number of devices for testing.
  • Limited Number of Apps: You are limited to sideloading a small number of apps onto your devices.

These limitations are generally manageable for individual developers or small teams learning and developing test automation. However, for larger-scale or continuous integration environments, a paid Apple Developer account is recommended.

Version 1.7.0