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:
You don't have to recompile your app or modify it in any way, due to use of standard automation APIs on all platforms.
- 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:
- Apple Developer Tools (iPhone simulator SDK, command line tools)
For Android automation:
- Android SDK API >= 17
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.
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
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):
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:
Manually modify the element following <allow-root> under <key>system.privilege.taskport</key> in your
/etc/authorizationfile to <true/>.
Run the following grunt command which automatically modifies your
/etc/authorizationfile for you:
sudo grunt authorize
At this point, you can simply run:
./reset.sh --ios --dev
Hacking with Appium (Android)
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):
Or you can run reset for individual platforms only:
./reset.sh --ios --dev ./reset.sh --android --dev ./reset.sh --selendroid --dev
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:
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
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,
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.)
Tapster and other robotsUsing with a
Check out the Appium Robots project
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.
Announcements and debates often take place on the Discussion Group, be sure to sign up!