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.
-
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!
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)
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
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.
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.
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
(First, have a look at setting up your system for Appium iOS support. Pay particular attention to the section on running multiple versions of Xcode, as Appium tests require this.)
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
(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>
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
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.
Like the power of automating dev tasks? Check out the Appium grunt tasks available to help with building apps, installing apps, generating docs, etc...
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.
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
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.
The open source community has made this project possible, please add missing projects to the list.
All the OSS code contributing to Appium
Announcements and debates often take place on the Discussion Group, be sure to sign up!