Set up Appium on macOS for Testing iOS Devices

Applies to TestComplete 15.65, last modified on July 17, 2024

The instructions below describe how to set up an Appium instance on a macOS machine and to configure it to manage iOS devices.


  • A macOS machine where the Appium server will be running. The supported Appium version is 2.x (recommended), 1.x (1.22.3 is advised if you need to use version 1.x).

  • The XCUITest driver must be installed on the Appium server. Please see the driver description in the Appium documentation:

    The XCUITest Driver for iOS

  • Your TestComplete computer must have network access to the macOS machine.

1. Install Homebrew, Carthage, and Node.js

  1. Install Homebrew (it’s a package management system that makes it easier to install software on Mac OS machines).

    Please find Homebrew and follow the instructions on this website:

  2. Install Carthage (a dependency manager). To do this, open the Terminal window and run the following command:

    brew install carthage
  3. Install Node.js and NPM. To do this, run this command:

    brew install node

2. Install Java

  1. Download the JDK from this website:

    Run the dowloaded installer and follow the instructions you will see on screen.

  2. Run the following command in the Terminal:

    /usr/libexec/java_home --v

    This will output a string like /Library/Java/JavaVirtualMachines/jdk1.8.0_171.jdk/Contents/Home. This is the location of the JDK on your computer. Copy this value.

  3. Open your .bash_profile file in an editor and add the following two lines to it:

    export JAVA_HOME="copied-path-to-JDK-directory"
    export PATH=$JAVA_HOME/bin:$PATH

    Save the changes.

    Restart the Terminal to grab the new .bash_profile settings.

3. Install Appium

You can do this in one of the following ways:

  • Install Appium Desktop. You can download the installer from this website:

    Please note that this method of installing Appium is neither recommended nor supported.

    — or —

  • Install Appium with npm. Run the following command in the Terminal window:

    npm install -g appium

Tip: We also recommend that you install the Appium Doctor in addition to Appium. It will help you fix issues with Appium and iOS settings easier. To install the Doctor, run the following command in the Terminal:

npm install -g appium-doctor

4. Install Xcode and Xcode command-line tools

  1. Download Xcode:

    Run the installer and follow the instructions you will see on the screen.

  2. To install Xcode command-line tools, run the following command in the Terminal:

    xcode-select --install

5. Install WebDriverAgent

WebDriverAgent is a WebDriver version for iOS. It serves for controlling iOS devices and apps remotely. You can find it in the following directories:

  • If you installed Appium Desktop:


  • If you installed Appium via Node.js:


To install:

  1. In the Terminal window, go to the directory specified above and run the following command:

    mkdir -p Resources/WebDriverAgent.bundle
    ./Scripts/ -d

  2. Open the WebDriverAgent.xcodeproj project in Xcode (you can find the project in one of the directories specified above).

    For the WebDriverAgentLib and WebDriverAgentRunner targets, go to the General tab and select the Automatically manage signing check box there, and then select your development team.

    It’s possible that Xcode will fail to create a provisioning profile for the WebDriverAgentRunner target. See below for information on how to fix this.

    See fixing instructions

  3. Build the project to verify that everything works fine:

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

    If the build fails because of the issues with the provisioning profile (the error message has the word “Provision”), the error message will mention the arguments to be specified in the command line. Modify the command line to make the build pass successfully.

    If you have physical devices connected to your Appium instance, then this command will output the list of device IDs. You can copy the ID of the needed device to specify it later in “capabilities” of your mobile tests. You can also get the ID any time later, see below.

  4. (Optional) Run the Appium Doctor to check if everything is configured properly. The Doctor will provide detailed information on issues, if any:


How to get device ID

If you are going to run tests on physical devices connected to your Appium instance, you need to specify the device ID in your test’s “capabilities”.

1. Install ios-deploy

Run the following command in the Terminal:

npm install -g ios-deploy

You need to perform this step only once.

2. Get the ID
  1. Connect your physical device to the Appium instance.

  2. On your computer, run the following command in the Terminal window:

    ios-deploy -c

    The command will output IDs of connected physical devices.

After Appium is set up and configured, you can connect to it from your TestComplete computer to create and run tests. See Connecting to Mobile Devices and Opening Testing Sessions.

See Also

Set up Appium Server

Highlight search results