Table of Contents

Appium is an open source test automation framework for use with native, hybrid and mobile Web applications. It drives iOS, Android, and Windows applications using the WebDriver protocol.

This procedure covers installation and configuration of Appium v.1.6.2+.

  1. Appium server installation

  2. Client use

  3. Useful links

Appium server installation

Android
Classic installation

Install Android SDK v.1.7+. See official documentation here and here for more details.

Docker install

+

# Note: It requires docker-compose 1.6.0+
#
# Usage: docker-compose up -d
version: '2'

services:
  # Selenium hub
  selenium_hub:
    image: selenium/hub:3.7.1
    ports:
      - 4444:4444

  # Appium Docker Android
  appium_android_device:
    image: appium/appium
    depends_on:
      - selenium_hub
    privileged: true
    volumes:
#      - /dev/bus/usb:/dev/bus/usb
      - ~/.android:/root/.android
      - ./localapk/:/apk/  # used to push apk to install
    ports:
      - 4723:4723
    environment:
      - CONNECT_TO_GRID=True
      - SELENIUM_HOST=selenium_hub
      # Enable it for msite testing
      #- BROWSER_NAME=chrom

+

IOS
Installation

  1. Install Xcode 8.1+

  2. Install the Apple Developer Tools via this external documentation

  3. Follow the complete procedure from this external documentation and apply the following commands and fixes:

    1. Carthage cannot be installed via npm but brew. Thus, install Carthage by executing:

      brew install carthage

    2. Execute the following additional commands:

      npm install -g ios-deploy --unsafe-perm=true
npm install -g deviceconsole
brew uninstall ideviceinstaller
brew uninstall libimobiledevice
brew install --HEAD libimobiledevice
brew unlink libimobiledevice && brew link libimobiledevice
brew install ideviceinstaller
brew unlink ideviceinstaller && brew link ideviceinstaller
      Caution
      Note about the current Appium version from npm

      At the time of writing, the installed Appium version (1.6.2) from the above procedure doesn’t work properly with Cerberus. Only the 1.6.3-SNAPSHOT version was able to correctly start application. The following commands will help you to install the latest version of Appium (extracted from the official documentation):

      git clone https://github.com/appium/appium.git
cd appium
npm install -g mocha
npm install -g gulp
npm install -g gulp-cli
npm install
gulp transpile
Application sign configuration

The latest version of Appium uses the appium-xcuitest-driver which depend on the Web Driver Agent that need to be deployed on the tested device. Thus, the Appium server’s host needs to be configured to be allowed to deploy application on tested device.

Appium server’s host must:

  1. Have its associated Apple account registered to a Apple Team Development

  2. Have downloaded the iOS Development signing identity associated to the registered Apple Team Development

  3. Have downloaded a provisioning profile associated to the registered Apple Team Development that allow:

    • at least the Web Driver Agent application (identified by the com.facebook.WebDriverAgentLib bundle identifier)

    • the tested device to install the Web Driver Agent application

Once all of these previous prerequisities are met, then create a appium.xcconfig file and fill it with the following lines (where <Team ID> is your Development Team identifier):

DEVELOPMENT_TEAM = <Team ID>
CODE_SIGN_IDENTITY = iPhone Developer

This file will be used further by execution. Look at the Run section for more details.

Run

Run Appium server can differ following the way you installed it.

Installation from npm

If Appium has been installed from npm, then simply starts Appium server by executing:

appium
Installation from Appium sources

If Appium has been installed from its sources, we encourage to create an executable file to start and configure Appium server more easily. Then:

  1. Create a appium file and fill it with the following lines

    #!/bin/bash
cd /path/to/appium/sources && node . "$@"

  2. Make this file executable

    chmod +x /path/to/the/appium/file

  3. Locate the root directory of this executable file and add it to your PATH variable by adding this line to your ~/.bash_profile (or any terminal session start) file:

    export PATH=/path/to/the/appium/file/root/directory:$PATH

  4. Restart your terminal session

  5. Start Appium server by executing

    appium
Note for IOS application testing

As viewed from previous section, Appium has to deal with Apple application sign. This could be done by sending the xcodeConfigFile capability to the Appium server.

But you may want to use the same value for any request, because the Apple Development Team is often unique within an organization. It could be the same for the realDeviceLogger capability because Appium can always using deviceconsole as real device logger.

This can be achieved by starting the Appium server with the --default-capabilities option and giving it the list of default capabilities. For maintenance reason, we recommend to delegate definition of the list of capabilities into a JSON file as the following:

  1. Create a file named common.caps (for instance)

  2. Fill it with your default capabilities

    {
    "xcodeConfigFile": "/path/to/appium.xcconfig",
	"realDeviceLogger": "/usr/local/lib/node_modules/deviceconsole/deviceconsole"
}

  3. Then start Appium server by executing

    appium --default-capabilities /path/to/common.caps

Client use

The following section will show different use cases to connect to the Appium server.

Execute mobile test case with Cerberus

Once you wrote your test case, Cerberus can execute it to the desired mobile by configuring the associated Robot

Inside Cerberus, open the Robot page (Run → Robot), and, depending on the application type, fill the Robot with the following configuration:

Android

Robot definition

Robot capabilities

Note
 Values are given as example. feel free to modify them according to your needs.
IOS

Robot definition

Robot capabilities

Note

Values are given as example. feel free to modify them according to your needs.

The two last capabilities xcodeConfigFile and realDeviceLogger are not necessary if given at Appium startup. See the previous section for more details.
Inspection

Inspection is used to locate application’s element by identifier, XPath, etc. Theses values can so be use inside Cebrerus to describe automated test cases.

Inspection can be done by using the Appium client interface.

Installation

Install latest client from the official page.

Configuration

Appium client interface has to be configured to be only used for inspection. to have application’s element XPath for instance):

From the General settings menu:

  • Fill the Server address input field with the Appium server address

  • Fill the Port input field with the Appium server port

  • Unable the Use Remote Server option

General settings

For Android case, open the Android settings menu and:

  • Fill the App Path with the absolute path (or URL) of the application APK

  • Fill the Platform Name by Android

  • Fill the Automation Name by Appium

  • Fill the Platform Version by your device platform version

  • Fill the Device Name by your device name

Android settings

For IOS case, open the IOS settings menu and:

  • Fill the App Path with the absolute path (or URL) of the application IPA

  • Fill the Force device input filed by your device name

  • Fill the Platform version input field by your platform version. It must be lower or equal than your Xcode SDK supported version (for instance, 10.1 by using Xcode 8).

  • Fill the UDID input field by your device’s UDID number

IOS settings

Run

Once Appium client is correctly configured, simply click on the Android or IOS radio button following the application definition and then click on the Inspector button.

Appium Inspector

Title Link

List of Appium server capabilities

https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md