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 1.20.0.
The XCUITest driver must be installed on the Appium server. Please see the driver description in the Appium documentation:
Your TestComplete computer must have network access to the macOS machine.
1. Install Homebrew, Carthage, and Node.js
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:
Install Carthage (a dependency manager). To do this, open the Terminal window and run the following command:brew install carthage
Install Node.js and NPM. To do this, run this command:brew install node
2. Install Java
Download the JDK from this website:
Run the dowloaded installer and follow the instructions you will see on screen.
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.
Open your .bash_profile file in an editor and add the following two lines to it:
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:
— 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
Run the installer and follow the instructions you will see on the screen.
To install Xcode command-line tools, run the following command in the Terminal:
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:
In the Terminal window, go to the directory specified above and run the following command:
mkdir -p Resources/WebDriverAgent.bundle
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 instructionsSee fixing instructions
The error text looks like this —
Failed to create provisioning profile...
No profile for '...' was found
To fix this issue, try changing the bundle ID for the target you use:
Go to the Build Settings tab page.
Change the Product Bundle Identifier value from —
– to –
where XXX is an arbitrary string.
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.
(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
Connect your physical device to the Appium instance.
On your computer, run the following command in the Terminal window:
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.