Engineering Insights & Mobile Solutions
Appium is an open-source, cross-platform test automation tool for native, hybrid, and mobile web apps, tested on simulators (iOS, FirefoxOS), emulators (Android), and real devices (iOS, Android, Windows).
This tutorial will cover all the necessary steps in order to have a setup on a macOS machine that is ready to run automated tests on an iOS device.
- A MacOS machine ( for this example we will use MacOS 10.12 )
- An iOS developer account that is added in the development team of the application under test
- Basic Java knowledge
The Setup process
1. Installing Java
Java can be downloaded from here. Click on Agree and download the .dmg file for Mac OS X and install it.
To check if the installation went well, open a terminal and type java -version. The output of the command should be similar to the below one:
2. Installing Node.JS
Go to the Node.js homepage, download the .pkg file and install it. When the installer has finished, it is stated that the path to local/bin should be added to the PATH variable. You can do that by following the next steps.
- Ensure that all hidden files are visible
- Open a terminal
- Type defaults write com.apple.finder AppleShowAllFiles YES
- Generate a bash_profile file:
- Open a terminal
- Type cd ~ in the terminal
- Type sudo nano .bash_profile and insert your password
- Save and quit the editing process of the bash profile
- Open the bash_profile, with a text editor and write the following line in it:
Type in a terminal npm -version to ensure that everything is ok. The output should be similar to the below one:
3. Installing Maven
Go to the Maven download page. Get the zip archive and extract it to your applications folder.
Now we must set the path variable for the bin folder.
To do that, go to the bash_profile file and add the following below the existing lines:
Exit the editor, open a terminal, and type: mvn -version.
The output should be similar to the below one:
4. Installing Xcode
Xcode is an integrated development environment for macOS containing a suite of software development tools developed by Apple for developing software for macOS, iOS, watchOS and tvOS
In order to install it, please access AppStore, search for XCode, and install it like any other app.
Open it and accept the license agreements.
5. Install a Java IDE
You can use any integrated development environment (IDE) that supports Java, in order to write tests. One of our favorite IDE is IDEA’s IntelliJ which can be downloaded from here for macOS.
6. Installing Appium Dependencies
Before starting to write tests in Appium, we must ensure that all dependencies are met.
The following dependencies are necessary:
- Homebrew – the easiest and most flexible way to install the UNIX tools that Apple didn’t include with macOS. To install it, run the below command from a terminal:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- Mobile device libraries – library and utility to talk to iBoot/iBSS via USB on Mac OS X. Run the below command:
brew install libimobiledevice --HEAD
These libraries will be needed for real devices in order to ensure communication between the macOS device and the iOS device.
- Carthage – a simple, decentralized dependency manager for Coco, the native object-oriented application programming interface (API) for macOS
brew install carthage
Carthage will be needed in order to install the application under test on the device.
- Ios-deploy Node.js library – used to install and debug iOS apps without using Xcode. Designed to work on un-jailbroken devices.
npm install -g ios-deploy
We will need this library to install the application under test.
- Appium Node.js library – this will be the framework for our tests
npm install -g appium
- WebDriver Agent – the WebDriver server implementation for iOS that can be used to remote control iOS devices.
And then issue the command:
/bin/bash Scripts/bootstrap.sh -d
WebDriver agent is basically an application that will be installed on the device used for testing and it has its own Xcode project. Running the .sh script will download all its dependencies.
7. Setting up Webdriver agent
Open WebDriverAgent.xcodeproj from the below location:
The targets for this project will require signing. To cycle through each one of them: WebDriverAgentLib, WebDriverAgentRunner, UnitTests, IntegrationTests, and IntegrationApp, select the General tab, click on “automatically manage to sign” and log in with your developer account.
This is how the signing section should be displayed:
8. Starting up a real device and getting ready for automatization
To start up a real device follow the below steps:
- Start a terminal and type appium. The appium server will start:
- Create an IntelliJ project, preferably with Maven support and the Appium dependency added.
- The below code is needed to start an app on a real device:
// creating some new capabilities DesiredCapabilities capabilities = new DesiredCapabilities(); //setting the automation name to XCUITest, this is needed as of 1.6.x capabilities.setCapability("automationName","XCUITest");
//device name should resemble the one from iTunes capabilities.setCapability("deviceName","iPhone"); //udid should be exactly the one from iTunes capabilities.setCapability("udid","UDID-OF-THE-DEVICE"); //the path to the ipa installer of the app capabilities.setCapability("app","PATH-TO-APP.ipa"); //platform name capabilities.setCapability("platformName","iOS"); //setting the URL, it must be the exact url as the one displayed when starting appium URL remoteAddress = new URL("https://0.0.0.0:4723/wd/hub"); //starting the driver with all the capabilities set appiumDriver = new IOSDriver(remoteAddress, capabilities);
And that’s it, the app will be installed and you will be ready for automation.
- Use USB 2.0, as the USB 3.0 support is still buggy
- Try doing the installation of the app under test manually first, as there may be permissions-related issues. These issues will cause failures when Appium tries installing the app on the device
- Use an iOS firmware higher than 10. Although 9.3 is the oldest supported version, using a version higher than 10 will generate more stable tests
- Stay updated with current Appium releases for bug fixes and improvements