Appium

Appium is an open source, cross-platform test automation tool for native and hybrid mobile apps. It supports iOS, Android, and FirefoxOS platforms. Appium drives Apple's UIAutomation library and Android's UiAutomator framework (for newer platforms) using Selenium's WebDriver JSON wire protocol. Appium's iOS support is based on Dan Cuellar's work on iOS Auto. Appium also comes bundled with Selendroid for testing older Android platforms.

Testing with Appium has two big benefits:

1. You don't have to recompile your app or modify it in any way, due to use of standard automation APIs on all platforms.

2. You can write tests with your favorite dev tools using Java, Objective-C, JavaScript, PHP, Python, Ruby, C#, Clojure, or Perl with the Selenium WebDriver API and language-specific client libraries. You can use any testing framework. If you use Apple's UIAutomation library without Appium you can only write tests using JavaScript and you can only run tests through the Instruments application. Similarly, with Google's UiAutomator you can only write tests in Java. Appium opens up the possibility of true cross-platform native mobile automation. Finally!

Requirements

General:

• OS X is required for iOS automation
  • Mac OS X 10.7 or higher, 10.8.4 recommended
• Android works on OS X and Linux. Support for Windows is in "beta"
• Node and npm (brew install node) (Node must be >= v0.8)

For iOS automation:

• XCode
• Apple Developer Tools (iPhone simulator SDK, command line tools)

For Android automation:

• Android SDK API >= 17 (Additional features require 18)

User Quick Start

Option 1: Use Appium.app:

• Download the Appium.app dmg
• Run Appium.app then run a test using your favorite language / framework

Option 2: Run Appium from the command line using Node:

mkdir appium-test && cd appium-test
npm install -g appium  # might have to do this with sudo
sudo authorize_ios # enable developer use of iOS sim
npm install wd
curl -O https://raw.github.com/appium/appium/master/sample-code/examples/node/simplest.js
appium &
node simplest.js

See the next section for links on how to make sure your system is set up to run Appium tests.

Example Tests: Node.js | Python | PHP | Ruby | Java

Troubleshooting

We put together a troubleshooting guide. Please have a look here first if you run into any problems. It contains instructions for checking a lot of common errors and how to get in touch with the community if you're stumped.

Write Tests for Your Apps with Appium

We support a sub-set of the Selenium WebDriver JSON Wire Protocol.

You find elements by using a sub-set of WebDriver's element-finding strategies. See finding elements for detailed information.

We also have several extensions to the JSON Wire Protocol for automating mobile gestures like tap, flick, and swipe.

You can also automate web views in hybrid apps! See the hybrid app guide

We support Android and iOS platforms side-by-side:

• Set up your system for Appium iOS support
• Set up your system for Appium Android support
• Set up your system for Android support on linux
• Prepare your app for an iOS test
• Prepare your app for an Android test
• Run an iOS test
• Run an Android test
• Getting started with Appium and Ruby on OS X

For the full list of Appium doc pages, visit this directory.

---

Hacking with Appium

Install node.js (includes npm, the node.js package manager). The recommended way to install node is brew install node. Node installed by brew will not require sudo for npm commands.

Fork the Appium repo ( https://github.com/appium/appium ), then clone your fork.

From your local repo's command prompt, install these packages using the following commands (if you didn't install node using homebrew, you might have to run npm with sudo privileges):

npm install -g mocha
npm install -g grunt-cli
./reset.sh --dev

The first two commands install test and build tools (sudo may not be necessary if you installed node.js via Homebrew). The third command installs all app dependencies, builds supporting binaries and test apps. reset.sh is also the recommended command to run after pulling changes from master. At this point, you're able to star the Appium server (see below for examples of various flags you can pass in):

node server.js

Hacking with Appium (iOS)

(First, have a look at setting up your system for Appium iOS support.)

To avoid a security dialog that may appear when launching your iOS apps you'll have to modify your /etc/authorization file in one of two ways:

1. Manually modify the element following <allow-root> under <key>system.privilege.taskport</key> in your /etc/authorization file to <true/>.

2. Run the following grunt command which automatically modifies your /etc/authorization file for you:

   sudo grunt authorize
   

At this point, you can simply run:

./reset.sh --ios --dev

Hacking with Appium (Android)

(First, have a look at setting up your system for Appium Android support (linux, osx or windows).)

Now, you can simply run:

./reset.sh --android --dev

If you want to use Selendroid for older apps:

./reset.sh --selendroid --dev

Make sure you have one and only one Android emulator or device running, e.g. by running this command in another process (assuming the emulator command is on your path):

emulator -avd <MyAvdName>

Making sure you're up to date

Since we use dev versions of some packages, it often becomes necessary to install new NPM packages or update various things. There's a handy shell script to do all this for all platforms (the --dev flag gets dev npm dependencies and test applications used in the Appium test suite):

./reset.sh --dev

Or you can run reset for individual platforms only:

./reset.sh --ios --dev
./reset.sh --android --dev
./reset.sh --selendroid --dev

Running Tests

Once, your system is set up and your code is up to date, you can run various kinds of tests:

grunt android
grunt ios
grunt selendroid
grunt firefoxos
grunt unit

Or you can run all tests:

grunt test

Before committing code, please run grunt to execute some basic tests and check your changes against code quality standards:

grunt
> Running "lint:all" (lint) task
> Lint free.
> Done, without errors.

Dig in deeper to Appium dev

Advanced grunt

Like the power of automating dev tasks? Check out the Appium grunt tasks available to help with building apps, installing apps, generating docs, etc...

Running individual tests

If you have an Appium server listening, you can run individual test files using Mocha, for example:

mocha -t 60000 -R spec test/functional/testapp/simple.js

Or individual tests (e.g., a test with the word "alert" in the name):

mocha -t 60000 -R spec --grep "alert" test/functional/apidemos

You can also run all of appium's tests this way. In one window, node server.js In another window, sequentially (waiting for each to pass, making sure emulator is up, etc...):

alias mm="mocha -t 60000 -R spec"

mm test/functional/apidemos
mm test/functional/prefs
mm test/functional/safari
mm test/functional/selendroid
mm test/functional/testapp
mm test/functional/uicatalog
mm test/functional/webview

For convenience, there's a test.sh script which runs just these tests which it is important to pass before publishing appium.

Advanced Appium server flags

Do you like getting close to the metal? Or are you trying to launch an Appium server from a script with a custom app? If so you can start Appium without grunt from the command line with an app or without an app, among other things:

node server.js // launch Appium server without app
node server.js --app /absolute/path/to/app  // launch Appium server with app
node server.js --launch // pre-launch the app when appium loads
node server.js --log /my/appium.log // log to file instead of stdout
node server.js --quiet // don't log verbose output

(See the server documentation for all CLI arguments.)

Using with a Tapster and other robots

Check out the Appium Robots project

Contributing

Fork the project, make a change, and send a pull request!

Oh and please have a look at our Style Guide before getting to work.

Project Credits & Inspiration

The open source community has made this project possible, please add missing projects to the list.

All the OSS code contributing to Appium

Mailing List

Announcements and debates often take place on the Discussion Group, be sure to sign up!