Skip to end of metadata
Go to start of metadata

Supported Environment

Appium1.6, 1.7 
Android6.x, 7.x 
iOS9, 10Not supported on Windows

Setup Guide

1. Prerequisites

  1.1 Libraries and application

/usr/bin/ruby -e "$(curl -fsSL"
brew install carthage
  • node and npm
brew install node
brew install npm
  • A Mac with Xcode and the Xcode Command Line Developer Tools.
  • An Apple Developer ID and a valid Developer Account with a configured distribution certificate and provisioning profile.
  • Your .ipa application must also be able to run on your device. The central requirements are the same: to have a build of your app (an .ipa file) signed with a development provisioning profile. A good overview of the process can be found here and here.

  1.2 Devices

  • An iPad or iPhone. Make sure this has been set up for development in Xcode. See this article for more information.
  • An Android device if you want to execute tests on it.

2. Setup environment

   2.1 Appium

Below command will install the latest version of Appium

npm install -g appium

If you with to install different version, then include version number (x.x.x) in this command:

npm install -g appium@x.x.x

   2.2 Xcode

Ignore this step if you just want to use Android device

  • Open Xcode > Preferences > Accounts: Add developer’s Apple ID

  • Open Terminal and enter following command to initialize WebDriverAgent project:

    cd /usr/local/lib/node_modules/appium/node_modules/appium-xcuitest-driver/WebDriverAgent
    mkdir -p Resources/WebDriverAgent.bundle
    sh ./Scripts/ -d
  • Open project WebDriverAgent.xcodeproj within folder WebDriverAgent in Xcode.

  • Select target WebDriverAgentLib, in the Signing section, check Automatically manage signing and select the team.

  • Then on the menu bar, select Product > Build

  • Repeat the last two steps for WebDriverAgentRunner

  • Xcode may fail to create a provisioning profile for the WebDriverAgentRunner target:

    Xcode provisioning fail

  • This necessitates manually changing the bundle id for the target by going into the "Build Settings" tab, and changing the "Product Bundle Identifier" from com.facebook.WebDriverAgentRunner to something that Xcode will accept:

    Xcode bundle id

  • Build WebDriverAgent to verify all above steps worked

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

    where <udid> is your Device ID

  • In case this dialog is displayed, select Always Allow.

  • If this was successful, the output should end with something like:

        Test Suite 'All tests' started at 2017-01-23 15:49:12.585
        Test Suite 'WebDriverAgentRunner.xctest' started at 2017-01-23 15:49:12.586
        Test Suite 'UITestingUITests' started at 2017-01-23 15:49:12.587
        Test Case '-[UITestingUITests testRunner]' started.
            t =     0.00s     Start Test at 2017-01-23 15:49:12.588
            t =     0.00s     Set Up
  • To completely verify, you can try accessing the WebDriverAgent server status (note: you must be on the same network as the device, and know its IP address, from Settings => Wi-Fi => Current Network)

    export DEVICE_URL='http://<device IP>:8100'
    export JSON_HEADER='-H "Content-Type: application/json;charset=UTF-8, accept:application/json"'
    curl -X GET $JSON_HEADER $DEVICE_URL/status
    You ought to get back output something like this:
          "value" : {
            "state" : "success",
            "os" : {
              "name" : "iOS",
              "version" : "10.2"
            "ios" : {
              "simulatorVersion" : "10.2",
              "ip" : ""
            "build" : {
              "time" : "Jan 23 2017 14:59:57"
          "sessionId" : "8951A6DD-F3AD-410E-A5DB-D042F42F68A7",
          "status" : 0

    3. Setup Devices

  • Android

    • Turn on the phone’s developer mode (go to Settings Developer options).
    • Connect your Android Phone to your computer via a USB cable. Just confirm if prompted for accepting/trusting the phone.

  • iOS 

    • Connect your iOS Devices to your computer via a USB cable. Just confirm if prompted for accepting/trusting the phone.
    • Enable the service UI automation on the device :
      • Connect the iOS device to Xcode 
      • Settings on the iOS device > Developer > turn ON UIAutomation
    • To test an iOS native application file (.ipa or .app file), make sure the application file is already built and signed properly to deploy on the device. Follow these steps to check if an application file is already built and signed correctly:
      1. Open Xcode and navigate to Window/Devices
      2. Choose your device from the Devices list
      3. Press the “+” button and choose you application file
      4. If installed successfully, the application will appear in the Installed Apps section as shown below.

Finishing steps

Once setting up successfully, follow the following guides to perform mobile testing in Katalon Studio

Troubleshoot common issues

Issue / Error Message

Root CauseSolution
xcodebuild exited with code '65' and signal 'null'Your .ipa application is not signed correctly.Sign and rebuild the WebDriverAgent XCode project with your developer certificate.
"Carthage not found" error message is displayedYou are using Appium 1.7 with Katalon Studio version less than Katalon Studio v5.1.0.2 to address this issue.
Real device is not displayed on device list of Katalon Studio

UIAutomation is not turned on


Check if UIAutomation is turned on:

  • Connect device to your Xcode
  • Settings on the iOS device > Developer > turn ON UIAutomation.


Credit to : 

with some adjustments to Katalon Studio settings

  • No labels