Appium for iOS and Android Automated Testing


On the very slim chance that you’ve found this blog, and you need to use Ruby and Cucumber to automate tests for web apps on Android and iOS? Here’s one way to get started. This is what I’ve been doing for the past few months.

Maybe sometime soon, I’ll have a repo with a nice Vagrantfile in it. If you’re vagrant savvy, you’ll just be able to clone it, type vagrant up and have a similar setup. We’ll see what happens…


If you get stuck, use stackoverflow, superuser, or any other Stack Exchange site like ask different. They are all amazingly helpful. Any knowledge of Ruby, the OS X (UNIX-like) command-line (for file permissions user groups, etc) will help you understand these instructions and get going in the right direction or get back on path if you’ve lost your way.

Tested with / Requirements

  • Macs with Lion OS and Mountain Lion OS
  • Ruby 1.9.3p448 (installed from binary)
  • Appium 0.8.2 (needed if you are using Lion), Appium 0.9.0 (Mountain Lion)
  • Chromedriver 2.1 (for Lion) or Chromedriver 2.2 (for Mountain Lion)
  • homebrew package manager
  • node.js
  • Install GenyMotion or the iOS simulator

note: administrative access required for part of setup

Installation and Configuration

Preliminary Setup: install XCode, the Command Line Tools and the iOS simulator

  1. Download XCode from the Apple Developer’s website.
  2. Install it from the package
  3. After the XCode install is complete, install the Command Line Tools and the Simulator:
    • Start XCode, open XCode Preferences (command+,) and select downloads. Click the install button for the command line tools and iOS. Wait for the long downloads and follow all dialogues to install.

Preliminary Setup: users and groups (admin access required)

  1. Setup groups for homebrew and automated test users: from terminal:
$ sudo dseditgroup -o create brew testers

Enter your password as needed (you must be an admin to use a sudo command.) 2. Add user to groups: This example uses supertester as an example user. You can replace that user with any user you need to add:

$ sudo dseditgroup -o edit -a supertester -t user testers
$ sudo dseditgroup -o edit -a supertester -t user brew

Install and configure homebrew package manager (admin needed)

  1. Visit the Homebrew website:
  2. Install Homebrew: Paste this at the terminal prompt: ruby -e "$(curl -fsSL"
  3. Change group for homebrew folder to ‘brew’: sudo chgrp -R brew /usr/local and type in your password.
  4. Give permissions to ‘brew’ group: sudo chmod -R 775 /usr/local
  5. Check to see that your permissions are working:
$ cd /usr/local/bin
$ touch my_test_file.tmp
$ ls

Look for the file ‘my_test_file.tmp’. If it is there, your permissions are set up correctly. Congratulations! Get rid of your test file: rm my_test_file.tmp

Install Appium

  • For a graphical user interface (needed if using Lion)
    1. Download the Appium Package and Install it by copying to Applications: The website is You will
  • For a command line install (possible if using Mountain Lion) same as above, or:
    1. Install node.js using brew: brew install node
    2. Install appium globally using node’s package manager ‘npm’: sudo npm install -g appium
    3. Use the package manager to install webdriver, too: npm install wd

Install Ruby from source

  1. Download libyaml: from
  2. Install libyaml:
    1. Go to the directory you downloaded it in, for example ‘~/Downloads’: cd ~/Downloads
    2. Unzip and untar it: tar zxvf yaml-0.1.4.tar.gz
    3. Enter the libyaml directory you extracted: cd yaml-0.1.4
    4. Enter these commands to install and wait while the source is compiled: configure && make && make install
      • If you want the mac to tell you when it is done, you can turn up your volume and type this in, instead: configure && make && make install && say "I am done"
  3. Download ruby: from mirror 1, mirror 2, mirror 3, mirror 4, or mirror5.
  4. Install ruby:
    1. Unzip it and untar it and enter the directory: tar zxvf ruby-1.9.3-p448.tar.gz && cd ruby-1.9.3-p448
    2. Compile source and install it using these commands: configure && make && make install
    3. Make a gem repository in your home directory: mkdir ~/mygemrepository
    4. Setup environment variables and paths: using ‘nano’, ‘vi’, or your text editor of choice:
      • Add export GEM_HOME=~/mygemrepository to the top of your ~/.bash_profile file.
      • Change your path so that it includes ‘~/mygemrepository/bin’ and so that ‘/usr/local/bin’ takes precedence over ‘/usr/bin’: you should make or edit a line in your ‘~/.bash_profile’ so that you have something like: PATH=/usr/local/bin:~/mygemrepository/bin:$PATH. It is important that ‘/usr/local/bin’ and ‘~/mygemrepository/bin’ be at the beginning of this line, as shown.
    5. Test to see that ruby is installed properly, and that you are using the correct version:
      • Type ruby -v at the command prompt. The output should include: ‘ruby 1.9.3p448’

Install Chromedriver

  1. Download Chromedriver
    1. Download if you have Mountain Lion or if you have Lion:
      • To see all downloads you will need to choose ‘All downloads’ from the dropdown in the search section and press the search button.
    2. Move chromedriver to a binary directory in your path:
      • Choose the download you need, unzip it, and from a prompt type (assuming you have it in ~/Downloads and downloaded 2.1:) cp ~/Downloads/ /usr/local/bin
    3. Test your installation:
      • Test it by typing, from a prompt: chromedriver
      • You should see ‘Started ChromeDriver (v2.1) on port 9515’
      • Troubleshooting Advice: If you see an error you can try downloading an earlier version.

Install the GenyMotion Android Emulator (needs admin access)

These instructions may change soon, so I’ll keep them short 1. Download and Install VirtualBox (needs admin access)

- Search for it on Google.
- Download it off the Oracle website.
- Open the package and follow the dialogues to install VirtualBox (it is required for the Genymotion Android Emulator)
  1. Setup Genymotion (current as of 09/16/13) and load the Chrome web browser onto it
    • Currently you need an account (free) with Genymotion to download or even install virtual machine images using Genymotion. Sign up for one.
    • Download the Genymotion installer for mac.
    • Install it using the dialogues.
    • Open Genymotion, log into the Genymotion cloud, and choose an image to download from the cloud. If you don’t know what to download, just make sure that the Android operating system is 4.1 or higher.
    • Click on the applications menu button and choose the ‘Play Store’ application.
    • Search for Chrome, and download it.

Android SDK Setup

  1. Download the SDK: Go to and click the ‘Download the SDK’ button.
  2. Install the SDK by following the directions
  3. Set up paths to Android Tools: Add these lines to the top of your ‘~/.bash_profile’:
export ANDROID_HOME=/usr/local/adt/sdk

Add these lines to the bottom of your ‘~/.bash_profile’:


These commands should now work without errors: adb and android

Appium Setup

Starting the Application if the GUI is installed

  1. Open the Appium application.
    • If using the Android emulator:
      1. Click the ‘Package’ checkbox after clicking the ‘Android’ tab
      2. Enter into the ‘Package’ text field
      3. Click ‘Launch’
    • If using the iOS simulator:
      1. Click the ‘iOS’ tab
      2. Check the box that says ‘Use mobile Safari’

Starting Appium from the Command Line

  1. For Android: At the terminal: appium --app-pkg
  2. For iOS: appium --safari

Sample Android Scripts to Test Your Setup:

These scripts should work with your setup, they are also available at They are written for Android. Connect your device or start your emulator before using these: Make a file called Gemfile with the following contents:

source ""
gem 'watir-webdriver'
gem 'selenium-webdriver'

Make a file called android_appium.rb with the following contents:

# Connect your device or start your emulator before running this script

# make sure appium and chromedriver aren't started yet.
#`killall node`
`killall chromedriver`
#start appium server for chrome pkg and redirect stderr and stdout to keep terminal clean
#`appium --app-pkg & > /dev/null 2>&1`
#prepare device
`adb kill-server`
`adb devices`
require 'fileutils'
require 'watir-webdriver'
require 'selenium-webdriver'

# The address and port of our Appium server
server_url = "http://localhost:4723/wd/hub/"

# Hash with information selenium webdriver needs 
capabilities =
      'app' => 'chrome',
      'device' => 'Android'

#Setup webdrivers to talk to Appium and mobile chrome and use implicit_waits to poll with long timeout to see if pages are loaded
driver = Selenium::WebDriver.for(:remote, :desired_capabilities => capabilities, :url => server_url)#, :profile => profile)
browser = driver
browser.driver.manage.timeouts.implicit_wait = 30
puts "new ANDROID Watir browser object instantiated"

#automated browser code using Watir browser object and methods
browser.goto ""
browser.text_field(:id=>"fbemail").set ''
sleep 1

#screenshot code
%x(adb shell /system/bin/screencap -p /sdcard/screenshot.png)
time =
puts 'current directory is' + `pwd`
%x(adb pull /sdcard/screenshot.png ./images/screenshot.png)'./images/screenshot.png', './images/screenshot' + time + '.png')
%x(adb shell rm /sdcard/screenshot.png)
`open images/.`

Credit Where Credit is Due

  • Matt Bussa
  • Pillar Technology
  • Dan Cuellar and Levi Wilson
  • Justin Lipps at Sauce Labs
  • And all the testers that know tons about Watir and Ruby: Alister Scott, Zeljko Filipin