GETTING STARTED

WITH APPIUM

By Jonathan Lipps

Ruby Edition 2018.1

3 The Preface

4 Ch. 1: Introduction

4 The Appium Vision

5 The Appium Drivers

8 Appium From the Command Line

8 Appium From Appium Desktop

10 Ruby Client Setup

10 Project Setup

11 Known Working Versions

12 Ch. 3: Exploring Your App

12 Using the Appium Ruby Console

17 Using the Appium Desktop Inspector

20 Ch. 4: Writing Your First Test

25 Ch. 5: Introduction to Page Objects

30 Ch. 6: Android Joins the Party

44 Creating an iOS Build

44 Running on Sauce

44 Jenkins for Production

46 Heading Out on Your Own

46 Resources

47 Support

TABLE OF CONTENTS

PREFACE

versions of various software are being used, which might help in ensuring

reproducibility of the code samples used here.

As the Appium project lead, I benefit from the work of the entire community

in being able to write a guide like this. Appium would not be what it is today

without the maintainers and users who have decided to throw their lot in

with our take on mobile automation. The credit for this book as well as for

Appium as a whole go far and wide! Thanks especially to Sauce Labs who

commissioned the writing of this guide, and @KazuCocoa, the current

maintainer of the Appium Ruby libraries.

Jonathan Lipps

server, which does the actual automating, and a set of Appium clients, one

for every popular programming language. You write tests in your favorite

language by importing the Appium client for that language and using its API

to define a set of test steps. When you run the script, those steps are sent

one-by-one to a running Appium server, which interprets them, performs

the automation, and sends back a result if appropriate.

Appium was initially developed to automate mobile applications, first iOS

and then Android. In recent years Appium has gone beyond mobile to

support Desktop or even TV apps. This guide focuses on mobile testing,

for iOS and Android.

windows which can show content from the web or from locally-stored

HTML files. Hybrid apps allow the use of web technologies within a

native-like user experience.

This guide focuses on automating native apps. Switching to web or hybrid

automation is a breeze once you’re familiar with the basic principles of

Appium automation, and plenty of information can be found online about

automating the other app modes.

THE APPIUM VISION

Appium is both more and less than an automation library. It is less than

an automation library because Appium itself relies on other, more basic

your Selenium knowledge will translate completely to Appium skill.

So Appium is fundamentally about providing you access to the best

automation technologies that are out there, within a standard WebDriver

interface accessible from any programming language or test client.

Importantly, Appium is totally open source. Owned by the JS Foundation,

Appium has open governance and contribution processes. The Appium team

believes that open is the way to go, and the meteoric rise of Appium as a

project is a testament to this approach.

THE APPIUM DRIVERS

How does Appium organize itself to meet its vision? Each automation

Appium in conjunction with one or more drivers. Even one platform (like

Android), might have multiple supported Appium drivers, which target

dierent fundamental automation technologies. For example, you can pick

between the appium-uiautomator2-driver and the appium-espresso-

driver when it comes to writing your Android tests. It’s worth getting to

know the dierent drivers so that you’re sure you’re using the best one for

your tests. While Appium does its best to ensure automation commands do

the same thing across dierent drivers, sometimes underlying dierences

make this impossible. For the Appium code samples in this guide, the iOS

driver we’ll be using is appium-xcuitest-driver, and the Android driver

nice user-facing methods (usually in an object-oriented fashion). This guide

will be using the Appium Ruby client, which is a rubygem named appium_lib.

the Selenium client, you’ll find it easy to understand the Appium version.

OK, time to get your system set up to run Appium tests!

depends on the various mobile SDKs and system dependencies in order

to perform its magic. This means that even if you’re not an app developer

yourself, and don’t plan on writing iOS or Android code, you’ll need to get

your system set up as if you were. Don’t worry—this guide will walk you

through it. I should point out for our Windows and Linux friends that this

guide assumes a Mac environment, since iOS testing can only be done on

a Mac. If you’re only interested in Android testing and want to run Appium

on Windows or Linux, refer to the Appium documentation for setup

information specific to your host OS.

ASSUMED KNOWLEDGE

that you know your way around the command line terminal on your Mac, and

already know the Ruby programming language well enough to follow along

with simple examples. If either of these assumptions are not true for you, stop

• Install Homebrew

• Install Carthage via Homebrew: brew install carthage

ANDROIDSPECIFIC SYSTEM SETUP

• Install Android Studio and SDK Tools

• Using the Android Studio SDK Manager, download the latest Android SDK,

build tools, and emulator images

• Install the Java Development Kit (JDK)

— Export $ANDROID_HOME to the location of the Android SDK on disk.

If you didn’t set this manually, it’s probably at the default location

— Ensure that the appropriate directories are added to your $PATH

so that the adb and emulator binaries are available from the

The particular device doesn’t matter. This will be the emulated device

we use for Android testing in this guide.

APPIUM SETUP

There are two ways to install ocially released versions of Appium: either

from the command line via NPM or by installing Appium Desktop.

Appium is shipped as a Node.js package, so if you have Node.js and NPM

installed on your system, you can simply run:

And the most recent version of Appium will be installed. You can then run

Appium simply by typing appium from the command line.

inspector tool, so you can simply download Appium Desktop without worrying

Strategy Description

Accessibility label

Internal id

UI class name

by the app developer across platforms, so they’re a good choice for a cross-

platform locator. From the output of the page command earlier, we know

we found the element we were looking for. If we wanted, we could also

If you watch the simulator while running this command, you’ll see the view

change as a result of the list item being tapped. We get an empty response

from arc because the click action doesn’t return any value; it simply does

its thing and gives back control. Let’s finish out this section by closing the

session (don’t want to leave it hanging around blocking future sessions or

hogging resources). We can simply type x at the arc prompt to achieve this.

Steps 2 and 3 simply repeat as many times as necessary to walk through your

app and generate the desired user behavior, making verifications in your test

code along the way. Of course, there’s a lot more to learn in terms of library

methods available to you. But this is the basic pattern. The rest is details!

Now, it’s up to you to go explore the Android version of The App. All you need

to do is fire up your AVD from Android Studio, and then run arc from the

android subdirectory in your project. If all goes well, you’ll be able to explore

the Android version of this app in exactly the same way as we did for iOS.

USING THE APPIUM DESKTOP INSPECTOR

pop up that will give you the ability to enter desired capabilities for a new

Appium session:

check your work. If you want, you can even save this set of caps so you can

load it next time you launch Appium Desktop. When you’re done, ensure that

the server selection panel has the correct server set (probably the “Automatic

Server” if you’re running from Appium Desktop). Then, click “Start Session”.

At this point Appium Desktop is starting a new session for you using the

The Inspector consists of four sections:

actions and features

2. A screenshot of the state of your app after the last command

3. The XML tree of your application hierarchy

and lets you interact with a selected element

In the screenshot section, you can move your mouse over dierent

elements and see them highlighted. If you click on one, it will open up in

the property viewer. Go ahead and click on the “Echo Box” list item. You’ll

screenshot and source refresh so we can explore the current state. (If the

app is slow and the refresh happens before new elements load, you can

always hit the ‘Refresh’ button to update the Inspector).

we can go into in this guide, including the ability to record test actions and

generate usable code. Please play with it and check out the Appium Desktop

README for more information. What we’ve learned to do with it so far is still

absolutely essential: how to navigate our app’s hierarchy and figure out which

selectors we should be using in our test code.

with the ability to figure out which elements are in our app and how to find

them, we can move to our favorite editor and write some Ruby scripts that

actually perform a useful verification.

“login” functionality of The App. It’s worth thinking first about how we would

test this manually before we begin to write code. Here’s what we’d do to

verify a successful login flow:

1. Open up the app

2. Tap the “Login Screen” item

3. Enter a valid username and password in the box

(Of course, to fully exercise the feature we’d also want a negative test:

entering an invalid username or password and ensuring that we cannot

if you don’t have it already:

Then, create a file called Gemfile in the root of our project directory.

The Gemfile will hold the description of the gems and their versions:

With this file in place we can run the bundle command in the project

root directory:

to develop our test suite. Now let’s compose our first test file, for iOS.

Create a file called login_spec.rb and add it to the ios directory:

You can run the test by navigating to the ios directory in your terminal

to fail just because Appium was too eager to try and find an element, and

then declared it to be non-existent, when it just needed to wait a few more

milliseconds! This is exactly what wait does: continually retries whatever is

in the block for up to 30 seconds by default.

What the rest of the code does should be pretty self-explanatory given what

we learned in the previous chapter. We’re finding elements using a variety

of locator strategies, and performing actions on them. The new action we

encounter in this code is send_keys, which sends keystrokes to an input field.

is hidden in the last chunk of the method. Telling Appium to wait until

an element exists with the string “You are logged in as alice” is a

verification, because if the element is present, we know we have reached the

information about our app (namely which elements can be found with which

locators) and information about our test (which test steps constitute the flow

we are trying to test). Another issue is that, as soon as we add a second login-

related test, we’ll begin duplicating our selector strings. Imagine if the app

were to change its accessibility IDs—we’d have to go make a change in many

dierent tests!

The common solution to these problems is to use something called the Page

Object Model. A Page Object represents a view, and exposes only high-level

actions so that test code can deal in user-level behaviors rather mixing in

low-level element finding logic. What do I mean by this? Imagine if the test

This is a much more concise, readable, and maintainable bit of test code. It

specifies everything we need to do, and nothing more than that. It puts the

responsibility of finding elements or getting data from them on these new

objects we’re referencing: @home_view, @login_view, and @user_view. These

represent the Page Objects that I have been talking about. Let’s take a look at

what a Page Object might look like for the home view:

Basically, we maintain the information about selectors in class variables, and

expose user-level behaviors in methods on the object. We encapsulate both

Great. The next bit of code reuse is to make sure that both iOS and Android

spec files use the same test code. Before, we had it in ios/login_spec.rb.

the block again. Notice also that our requires.rb is now in this same base

the appropriate before and after methods, and then we’re simply mixing in

the desired test behavior as the login_with_valid_credentials method.

As we write more tests, we can simply add their method calls here.

Model. We now need two versions, because we can’t, unfortunately, use com-

pletely identical locators across platforms. We can, however take advantage of

Ruby’s class inheritance to only change what we absolutely must:

And then, because we’ve made everything totally cross-platform, we can run

the same test on Android:

Don’t forget to launch your emulator before attempting to run the test! And

that’s it. Of course, if you aren’t dealing with a cross-platform app in your own

testing, you may not want to go to such lengths to share code the way we did

here. We went through this exercise to drive home the point that it’s possible,

and a good idea, to think about your test code as a software product just as

much in need of refactoring and code reuse as your app itself. Keep it clean

directly. But Ruby projects often use a task runner called rake (Ruby’s version

of Make), which comes with some niceties for command line execution of

tasks like our tests. Let’s upgrade our project for use with rake.

First, we need to add rake to our Gemfile:

Make sure to run bundle install at this point to get the new gem on your

system. Now we can build a Rakefile which specifies the kinds of tasks we

want rake to run for us:

appropriate arguments to make it run any spec files it finds nearby. To make

sure our Rakefile is put together correctly, we can query it for tasks:

successfully. Next, we’ll move on to adding more rake tasks and running our

tests in the cloud!

that it’s impractical to run locally on your own machine, or requires platforms

you no longer have easy access to. For these and a variety of other reasons,

it’s a good idea to invest in cloud Appium providers like Sauce Labs. appium_

advantage of this support, we’ll need:

one, you can start a free trial here, and find your access key at your

dashboard after login)

Let’s update our Gemfile accordingly (and run bundle install):

In order to make our test app accessible to the Sauce cloud,

Sauce-specific test setup and app uploading:

we’re using capabilities that are valid on Sauce. We also need to add the

choose between any version of Appium currently hosted on the provider.

you through getting the capabilities for the platforms you need. Using this

tool, I’ve updated the appium.txt files (and also removed our hack to prevent

tests from running on Sauce before we wanted to).

And for Android:

To successfully run a test on Sauce, we now need to first ensure our

environment variables are set correctly. We can do this in our terminal

using the following commands:

This will store the variables for the duration of the current terminal session.

If you want to store them permanently, it’s a good idea to add the export

commands to your ~/.bashrc, ~/.bash_profile, ~/.zshrc, etc…, shell login

file. That way you never have to remember them again.

Now, we can use our new rake task parameters to decide whether we want

the Sauce Labs website and you can see the tests running on your dashboard.

If you click on a test, you will be greeted with a variety of details about

it, including a stream of the running test (or a video if you catch it after it

we know our test passed. Let’s fix that.

ANNOTATING TESTS ON SAUCE

By default, Sauce doesn’t know what our test is called, or whether it passed

on our Sauce dashboard.

Let’s once again upgrade our spec_helper.rb. This time we just need to

modify the before(:each) and after(:each) blocks to take a parameter

we’ll call test. This is RSpec’s way of giving us access to information about

see a beautiful green checkmark when the test passes (or a correspondingly

At this point, we’ve got a very robust and flexible setup that can work well for

local development as well as extend to the cloud. The last step in our journey

is to set our tests up to be run as part of a Continuous Integration server.

they are run. The ideal scenario is for your entire test suite to be run on every

single code change, so that changes are gated on passing the entire test suite.

Why allow code in to your app if it breaks something?

The way many teams work this out in practice is by using a “CI server”.

CI stands for “Continuous Integration”, and refers to the process whereby

new code is constantly added to the shippable version of your app. Typically

developers use a branching version control system with one branch (master

In other words, master is always primed for release. Developers work on

their own forks or branches, and before their code is merged to master, it

in: from an automated testing perspective, the CI server is responsible for

figuring out when new code needs to be tested, testing that code, and then

merging code which passes the tests into the main trunk. Of course, the CI

server can do a whole lot more, for example building artifacts used in testing

or for eventual release.

of Jenkins in this chapter, to see how easy it is to configure tests to run in CI.

You could follow homebrew’s instructions and set up Jenkins to run on

server start, but since we’re just playing around, let’s instead run an instance

of Jenkins right here from the command line:

Sauce Labs ensures the world’s leading apps and websites work flawlessly on every browser, OS and device. Its award-

winning Continuous Testing Cloud provides development and quality teams with instant access to the test coverage,

scalability, and analytics they need to deliver a flawless digital experience. Sauce Labs is a privately held company

funded by Toba Capital, Salesforce Ventures, Centerview Capital Technology, IVP and Adams Street Partners. For more

information, please visit saucelabs.com.

ABOUT SAUCE LABS