iOS Software - Selenium hub & Appium nodes

This documentation will guide you in installing a mobile 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
  • Selenium server 3.141.59
  • Appium 1.13.0
  • Appium-Doctor 1.6.0

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.

Selenium server

Install Selenium server 3.141.59 using this command :

brew install selenium-server-standalone@3.141.59

You can check the version using :

selenium-server -version

Appium server

You may install different versions of Appium (for example, Appium 1.13.0 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.13.0 --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

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 IP address and the port of the Appium node
  • the IP address and the port of the Selenium hub

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.

How to get IP address ?

To get the IP address of Selenium hub, run the command below in a terminal on the computer you will start the Selenium server :

ifconfig

If you want to launch an Appium node on a different computer, run this command on the computer you will start the Appium server.

Start the platform

First, you have to run Selenium server in hub mode in a terminal. By default it’s running on 4444 port but you can change it using -port option :

selenium-server -role hub -port 4445

You should see the following message :

15:50:10.631 INFO [GridLauncherV3.parse] - Selenium server version: 3.141.59, revision: e82be7d358
15:50:10.735 INFO [GridLauncherV3.lambda$buildLaunchers$5] - Launching Selenium Grid hub on port 4445
2019-09-04 15:50:11.155:INFO: main: Logging initialized @855ms to org.seleniumhq.jetty9.util.log.StdErrLog
15:50:11.354 INFO [Hub.start] - Selenium Grid hub is up and running
15:50:11.355 INFO [Hub.start] - Nodes should register to http://xx.xx.xx.xx:4445/grid/register/
15:50:11.355 INFO [Hub.start] - Clients should connect to http://xx.xx.xx.xx:4445/wd/hub

You also can check if your hub is running going to http://xx.xx.xx.xx:4445/grid/console

Now, make sure your phone is connected to the computer and run an appium server in node mode in a terminal :

/path/to/appium --nodeconfig /path/to/ios-node-config-file.json --port 47XX --webkit-debug-proxy-port 277XX --default-capabilities '{"wdaLocalPort": 80XX }'

You should see the following message :

[Appium] Welcome to Appium v1.13.0
[Appium] Non-default server args:
[Appium]   port: 47XX
[Appium]   nodeconfig: path/to/ios-node-config-file.json
[Appium]   webkitDebugProxyPort: 277XX
[Appium]   defaultCapabilities: {
[Appium]     wdaLocalPort: 80XX
[Appium]   }
[Appium] Default capabilities, which will be added to each request unless overridden by desired capabilities:
[Appium]   wdaLocalPort: 80XX
[debug] [Appium] Starting auto register thread for grid. Will try to register every 10000 ms.
[Appium] Appium REST http interface listener started on 0.0.0.0:47XX
[debug] [Appium] Appium successfully registered with the grid on http://xx.xx.xx.xx:4445
[HTTP] --> GET /wd/hub/status
[HTTP] {}
[debug] [GENERIC] Calling AppiumDriver.getStatus() with args: []
[debug] [GENERIC] Responding to client with driver.getStatus() result: {"build":{"version":"1.13.0"}}
[HTTP] <-- GET /wd/hub/status 200 4 ms - 68

In the Selenium server terminal, you should see this message attesting the node is well connected to hub :

15:56:12.969 INFO [DefaultGridRegistry.add] - Registered a node http://xx.xx.xx.xx:47XX

You must see a new node connected in the hub grid : http://xx.xx.xx.xx:4445/grid/console

If the connection is not established, you may have to check the state of the firewall, which can be problematic.

Automate servers launch (optional)

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

. run-selenium-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-selenium-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.