Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Reverted from v. 75

Supported Environment

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

Setup Guide


  • MacOS computer for using in Appium with iOS
  • Apple developer account for setting up Appium with iOS
  • iPad or iPhone for using in sample script.

Installing dependencies

Setup MacOS environment

Download and Install Xcode updated version (prefer)

Apple’s XCode development software is used to build Mac and iOS apps, but it also includes the tools you need to compile software for use on your Mac. XCode is free and you can find it in the Apple App Store.

Install via App Store

Image Removed

Install via terminal

Image Removed

Configuration command-line tool Xcode

Image Removed

Image Removed

Image Removed

Download and Install NodeJS and npm package module updated version (prefer)

Installing NodeJS

Before you can install Node, you’ll need to install Homebrew applications:

Homebrew is a package manager for the Mac — it makes installing most open source sofware (like Node) as simple as writing brew install node. You can learn more about Homebrew at the Homebrew website. To install Homebrew just open Terminal and type 

Code Block

1. Prerequisites

  1.1 Libraries and application

Code Block
/usr/bin/ruby -e "$(curl -fsSL
You’ll see messages in the Terminal explaining what you need to do to complete the installation process.
  • Installing Node.js and NPM is pretty straightforward using Homebrew. Homebrew handles downloading, unpacking and installing Node and NPM on your system. The whole process (after you have XCode and Homebrew installed) should only take you a few minutes.

  • Open the Terminal app and type

    Code Block
    brew install node


    Installing WebDriverAgent to iOS devices

    Alternatively, the provisioning profile can be manually associated with the project (keep in mind that this will have to be done each time the WebDriverAgent is updated):

    • Find out where your Appium installation is (we will you that path to open WebDriverAgent's project):

    Image Removed

    Given this installation location, /path/where/installed/bin/appium, WebDriverAgent will be found in /path/where/installed/
    Code Block
    brew install carthage
    • node and npm
    Code Block
    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

    Code Block
    npm install -g appium

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

    Code Block
    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

      Image Added

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

      Code Block
      cd /usr/local/lib/node_modules/appium/node_modules/appium-xcuitest-driver/WebDriverAgent
      mkdir -p Resources/WebDriverAgent.
      Open a terminal and go to that location, then run the following in order to set the project up:
      Image Removed

      Create bundle folder and download all dependencies for WebDriverAgent project:

      WebDriverAgent bundle


      mkdir -p Resources/WebDriverAgent.bundle # command to create Resources folder with nested fodler 
      ./Scripts/ -d # command to download all dependencies



      titlecommon issues

      Error code 13: re-run command with sudo: sudo ./Scripts/ -d

      Error Error StackTrace: Cannot find module 'eslint-config-appium': missing paramter -d when running ./Scripts/


    • Open WebDriverAgent.xcodeproj using Xcode
    Create a provisioning profile for the WebDriverAgentRunner:
    For both the WebDriverAgentLib and WebDriverAgentRunner targets, select "Automatically manage signing" in the "General" tab, and then select your Development Team. This should also auto select Signing Ceritificate.
    Image Removed

    After we have done the configuration then we build the project to verify it works

    Image Removed

  • Deploy WebDriverAgent to iOS device
    Image Removed
    Image Removed




    • By default the project includes unit tests and integration tests but we can remove it (in gif above we only have WebDriverAgentLib and WebDriverAgentRunner).
    • Make sure WebDriverAgentRunner has enough dependencies libraries (In case we miss dependencies libraries we can get the error Error Domain=IDETestOperationsObserverErrorDomain Code=6). Below is full dependencies for WebDriverAgentRunner:

    Image Removed

    You can terminate the deploy process if it shows the log information "WebDriverAgentRunner-Runner[266:7829] Built at xxx"
    Image Removed
    • bundle
      sh ./Scripts/ -d
    • Open project WebDriverAgent.xcodeproj within folder WebDriverAgent in Xcode.
      Image Added

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

    • Then on the menu bar, select Product > Build
      Image Added

    • Repeat the last two steps for WebDriverAgentRunner

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

      Xcode provisioning failImage Added

    • 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 idImage Added

    • Build WebDriverAgent to verify all above steps worked

      Code Block
      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.
      Image Added

    • 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)

      Code Block
      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
      Code Block
      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
          Image Added
        4. If installed successfully, the application will appear in the Installed Apps section as shown below.
          Image Added

    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

    Table of Contents