iOS Software - Appium servers only

This documentation will guide you in installing a mobile testing platform (software part) using a Selenium Hub and Appium nodes for iOS phones.

List of prerequisites :

  • a computer with macOS Mojave (minimum version : 10.14.0)
  • administrator rights

What you will need to install :

  • Xcode 10.3
  • JDK 1.8
  • Node.js 8.12.0
  • npm 6.4.1
  • Appium 1.14.2
  • Appium-Doctor 1.6.0
  • ios-webkit-debug-proxy 1.8.5

Tools installation

Xcode

Download and install Xcode 10.3 from Apple Developer.

JDK

Download and install JDK 1.8 from Oracle website and add the environment variable :

export JAVA_HOME=$(/usr/libexec/java_home)
export PATH=${JAVA_HOME}/bin:$PATH
source .bash_profile

Node.js

Download and install Node.js 8.12.0 from here. You can check the version using :

node -v
npm -v

Homebrew

Install homebrew followig instructions of Homebrew hompage.

Appium server

You may install different versions of Appium (for example, Appium 1.14.2 for iOS part and Appium 1.8.1 for Android part), so we recommend that you do not install Appium in global mode. Create a folder /AppiumiOS somewhere and then run the following command to install Appium :

npm install appium@1.14.2 --save

If you will use an unique version of Appium, you can install Appium server in global mode using the option -g.

Appium Doctor

Install Appium Doctor :

npm install -g appium-doctor

and then run the following command to check if all prerequisites are installed for Appium :

appium-doctor

Other tools

Install usbmuxd using this command :

brew install --HEAD usbmuxd

Install libimobiledevice following instructions from Libimobiledevice Github.

Install ios-deploy using this command :

npm install -g ios-deploy

Install ios-webkit-debug-proxy using this command :

brew install --HEAD ios-webkit-debug-proxy

You have to use --HEAD option to get the most recent version (version 1.8.5 required, link to the formula page). To check the ios-webkit-debug-proxy version, use this command :

ios_webkit_debug_proxy --version

See more information.

Web Driver Agent

You have to change the project signature of WebDriverAgent project at /AppiumiOS/node_modules/appium-xcuitest-driver/WebDriverAgent/. See more information.

Appium node configuration

You will need to create a configuration file for each phone you want to connect. You can find an example of configuration file in /nodes folder. This file is composed as follows. You have to change some information in this sample file :

  • the device name
  • the device UUID
  • the iOS version on the device
  • the port you want to use

How to get UUID ?

Plug your phone into an USB port and open iTunes. MacOS will ask for the rights to access the phone, always accept. Go to the view of the device then click on “Serial number” to display the UDID. See how to get UDID for iPhone XR, XS or XS Max.

Start the platform

Make sure your phone is connected to the computer and run an appium server in a terminal :

/path/to/appium --default-capabilities /path/to/ios-node-config-file.json --port 47XX

You should see the following message :

[Appium] Welcome to Appium v1.14.2
[Appium] Non-default server args:
[Appium]   port: 47XX
[Appium]   webkitDebugProxyPort: 277XX
[Appium]   defaultCapabilities: {
[Appium]     capabilities: {
[Appium]       0: {
[Appium]         browserName: safari
[Appium]         deviceName: iPhone X
[Appium]         maxInstances: 1
[Appium]         platform: MAC
[Appium]         udid: 1a2b3c4d5e6f
[Appium]       }
[Appium]     }
[Appium]     platformVersion: 12.4,
[Appium]     wdaLocalPort: 80XX
[Appium]   }
[Appium] Default capabilities, which will be added to each request unless overridden by desired capabilities:
[Appium]   capabilities: {
[Appium]     0: {
[Appium]       browserName: safari
[Appium]       deviceName: iPhone X
[Appium]       maxInstances: 1
[Appium]       platform: MAC
[Appium]       udid: 1a2b3c4d5e6f
[Appium]     }
[Appium]   }
[Appium]   platformVersion: 12.4
[Appium]   wdaLocalPort: 80XX
[Appium] Appium REST http interface listener started on 0.0.0.0:47XX

Automate servers launch (optional)

In the /scripts folder you will find a script that will launch the Appium nodes. After modifying the path, you can start the script running this command in a terminal :

. run-appium-servers-for-ios.sh

To go further, you can schedule the server launch by defining a cron job. To see the list of your cron jobs, run the command :

crontab -l

To add a new entry in the crontab, run this command :

crontab -e

Edit the file, adding this line in order to launch the script at 9AM every week day :

0 9 * * 1-5 . /Users/path/to/run-appium-servers-for-ios.sh

Learn more about cron expression here : https://crontab.guru/

Phones setup (optional)

To improve the use of the platform and make it as autonomous as possible, you can :

  • disable the phone pausing

Web Inspector

To activate web inspector on iPhone, go to Settings > Safari > Advanced and enable Web inspector.