Skip to end of metadata
Go to start of metadata

Supported Environment

Appium1.6, 1.7 
Android6.x, 7.x 
iOS9, 10,11Not 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
  • A Mac with Xcode and the Xcode Command Line Developer Tools.
  • A valid iOS Development Certificate and Provisioning Profile are necessary to test on a real device. Your app will also need to be signed. You can find information about this in the Apple documentation.
  • 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.
    • If you want to execute your tests using Safari on iOS (mobile browser), make sure Web Inspector is turned on for Safari (Settings → Safari → Advanced → Web Inspector)
    • 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 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 and/or WebDriverAgent is not signed correctly.


Sign and rebuild the WebDriverAgent XCode project with your developer certificate.

Uncheck 'Automatically Signing' option from WebDriverAgentRunner and select valid provisioning profile (profile displayed as Eligible from the list)

"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.


For more issues, please refer to this troubleshoot tutorial

Credit to : 

with some adjustments to Katalon Studio settings

  • No labels