Skip to main content

[Mobile] Install WebDriverAgent for real iOS devices in Katalon Studio

The WebDriverAgent is a WebDriver server used to control iOS devices remotely. It is automatically downloaded with Appium as appium-webdriveragent.

When testing iOS applications with real iOS devices, you need to install WebDriverAgent on your development machine.

In this article, we demonstrate how to install the WebDriverAgent via Katalon built-in tools and manual installation.

Requirements

  • You have set up real iOS devices for mobile testing. See [Mobile] Set up iOS real devices .

  • You have enrolled in the Apple Developer Program. To learn more about the Apple Developer Program enrollment, you can refer to this Apple document: Enrollment.

Install the WebDriverAgent with Katalon built-in tools

You can install the WebDriverAgent with Katalon built-in tools. Follow these steps:
  1. Download and install a signing certificate and provisioning profile generated from an Apple Developer Account on your development machine. You can manage your signing assets via Xcode. Refer to the following Apple documents for further information:
  2. Open Katalon Studio and go to Tools > Set up iOS environment > Install WebDriverAgent.
    Install WebDriverAgent via Katalon built-in tools
  3. In the iOS Devices dialog, select the real iOS device you want to test then click OK.
  4. In the Provisioning Profile and Development Identity, select the desired profile and development identity.
    Katalon installs WebDriverAgent
Katalon Studio builds the WebDriverAgent for you.

Install the WebDriverAgent manually

To install the WebDriverAgent manually, follow these steps:
  1. In Xcode > Preferences > Account click Add (+) to enter your Apple Developer Account ID and password.
  2. To navigate to the location of the WebDriverAgent, open Terminal, copy and paste the command below:
    For Appium version 2.x:
    cd /Users/your_username/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj
    
    
    For example:
    cd /Users/john_smith/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj
    For Appium 1.22.2, use the following command:
    cd /usr/local/lib/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj

  3. After going to the WebDriverAgent location, run the following command to initialize the WebDriverAgent project:
    mkdir -p Resources/WebDriverAgent.bundle
    For Appium version older than 1.20.0, you also need to run the following script on the same terminal:
    sh ./Scripts/bootstrap.sh -d
    Note:
    • Error code 13: re-run command with sudo:
      sudo./Scripts/bootstrap.sh -d
    • Error _Error StackTrace: Cannot find module 'eslint-config-appium': missing parameter -d when running /Scripts/bootstrap.sh.

  4. Open Finder and type appium-webdriveragent to quickly search for the folder. In the opened folder, double-click the WebDriverAgent.xcodeproj file to open it in Xcode.
  5. After opening WebDriverAgent.xcodeproj file in Xcode, you need to build the IntegrationApp app. To do so, follow these steps:
    1. Select the IntegrationApp target. In the Signing & Capabilities section, check the Automatically manage signing box, then choose a team added in Step 1.
      Configure the IntegrationApp target

    2. On the menu bar, select Product > Build.
      Build the IntegrationApp target

    You have successfully built the IntegrationApp target.
  6. Next, build the WebDriverAgentLib target. Follow these steps:
    1. Select the WebDriverAgentLib target. In the Signing & Capabilities section, check the Automatically manage signing box, then choose a team added in Step 1.
      Configure the WebDriverAgentLib target

    2. On the menu bar, select Product > Build.
      Build the WebDriverAgentLib target

    You have successfully built the WebDriverAgentLib target.
  7. Finally, you need to build the WebDriverAgentRunner target. Follow these steps:
    1. Select the WebDriverAgentRunner target. In the Signing & Capabilities section, check the Automatically manage signing box, then choose a team added in Step 1.
      Configure the WebDriverAgentRunner target

    2. On the menu bar, select Product > Build.
      Build the WebDriverAgentRunner target

You have successfully manually installed the WebDriverAgent.