Getting started with Selendroid

Selendroid is based on the Android instrumentation framework. Currently only the testing of one specific app is supported. Selendroid requires the following permission for your app:

<uses-permission android:name="android.**permission.INTERNET"/>

System Requirements

  1. Selendroid can be used on Mac, Linux and Windows.
  2. Java SDK (minimum 1.6) must be installed and JAVA_HOME configured. IMPORTANT: If JAVA_HOME is pointing to a Java runtime environment, selendroid will produce errors because tools like the jarsigner are not available!
  3. Latest Android-Sdk must be installed and ANDROID_HOME set. If detailed instructions are needed, have a look at this guide.
  4. If you run selendroid on a 64bit Linux machine, please install:
    1. sudo dpkg --add-architecture i386
    2. sudo apt-get update
    3. sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386
  5. At least one Android virtual device must exist or an Android hardware device must be plugged in to the computer. For best practices about Android devices please read this section.

Getting an application under test

Selendroid can be used to test already built apps. Those Android apps (apk file) must exist on the machine, where the selendroid-standalone server will be started. The reason for this is that a customized selendroid-server for the app under test (AUT) will be created. Both apps (selendroid-server and AUT) must be signed with the same certificate in order to install the apks on the device.

If you want to play around with selendroid, you can use our selendroid-test-app which we use to verify that actually selendroid works as expected. You can download this app here.

Launching Selendroid

Download selendroid-standalone.jar and cd to the folder where you downloaded the jar, and run:

java -jar selendroid-standalone-0.17.0-with-dependencies.jar -app selendroid-test-app-0.17.0.apk

Selendroid-standalone will start a http server on port 4444 and will scan all Android virtual devices (avd) that the user has created (~/.android/avd/). The Android target version and the screen size will be identified. If an emulator is running, it can be used since version 0.11.0. Even an emulator that has been started manually after the selendroid-standalone got started can be used. If there are Android hardware devices plugged in, they will also be added to the device store.

You can check that the application(s) and the devices are recognized by opening a browser and navigating to: http://localhost:4444/wd/hub/status.

You should see a result similar to this:

  status: 0,
  value: {
  "os": {
    "name": "Android"
  "build": {
    "browserName": "selendroid",
    "version": "0.17.0"
  "supportedApps": [{
    "appId": "io.selendroid.testapp:0.17.0",
    "mainActivity": "io.selendroid.testapp.HomeScreenActivity",
    "basePackage": "io.selendroid.testapp"
  "supportedDevices": [{
    "screenSize": "320x480",
    "targetPlatform": "ANDROID17",
    "emulator": true,
    "avdName": "latest"
  }, {
    "screenSize": "320x480",
    "targetPlatform": "ANDROID16",
    "emulator": true,
    "avdName": "es"
  }, {
    "screenSize": "320x480",
    "targetPlatform": "ANDROID10",
    "emulator": true,
    "avdName": "AVD_for_api10"

Selendroid-Standalone command line parameters

-h, --help
Prints usage instructions to the terminal.
Specify the port for selendroid-standalone to run on, the default is 4444.
-app, -aut
Specify the location of the application under test. Absolute path expected.
Specify the timeout in milliseconds to start emulators, the default is 300000.
Specify the port number to start running emulators on.
This enables screenshots to be taken on the device instead of using the ddmlib library.
Specify the port the selendroid-standalone is using to communicate with instrumentation server, default is 8080.
Specifies whether or not adb logging should be enabled for the device running the test.
Specifies the log level of selendroid. Available values are: ERROR, WARNING, INFO, DEBUG and VERBOSE. Default: ERROR
Specify the file of the keystore to use.
The alias of the keystore to be used
The password for the keystore to be used
Specify the emulator options used for starting emulators: e.g. -no-audio.
Specify if you don't want selendroid to auto-extract and have 'AndroidDriver' (webview only app) available.
Specify if user data should not be cleaned after the test session has ended.
Specify the maximum session duration in seconds. Session will be forcefully terminated if it takes longer. Default is 30 minutes.
Maximum time in milliseconds to wait for the selendroid-server to come up on the device. Default: 20000
Specify and adb will not be terminated on server shutdown.
Specify to send a registration request to the given (Selenium grid hub) url. Example : http://localhost:4444/grid/register
Specify the remote proxy to use on the grid. Example : io.selendroid.grid.SelendroidSessionProxy
Specify host of the node. Ip address needs to be specified for registering to a grid hub (guessing can be wrong complex).
Specify an absolute path of a folder that will be monitored for new apps (.apk files) to sign and add to the app store. Can be ignored if not needed.

First Tests

Tests are written using the Selenium 2 client API. For Java we provide selendroid-client libraries that are used in the following example:

SelendroidCapabilities capa = new SelendroidCapabilities("io.selendroid.testapp:0.17.0");

WebDriver driver = new SelendroidDriver(capa);
WebElement inputField = driver.findElement("my_text_field"));
Assert.assertEquals("true", inputField.getAttribute("enabled"));
Assert.assertEquals("Selendroid", inputField.getText());

If, for example, you prefer to write your tests in Python, the same test can be found here, and here in Ruby.

In order to create a new test session in the desired capabilities, the id of the app under test must be provided in the format: io.selendroid.testapp:0.17.0. Please note, if the version is not specified in the id of the app under test then the latest version of the app will be automatically selected. Based on that information a matching Android device will be identified, otherwise the test session will throw an error and not start. Important: before filing a bug: please make sure the desired capabilities in your test match the supported apps and devices available.

After the found device has been initialized, a customized selendroid-server will be created and automatically installed on the device. The app under test will also be installed and the selendroid-server on the device will then be automatically started.

After the test session has been successfully initialized, the test commands such as 'find an element' and 'element interactions' are routed to this device. If the test session has ended, the emulator will stop automatically.

Desired Capabilities (SelendroidCapabilities)

Mandatory properties

We recommend the use of SelendroidCapabilities. There you find convenient methods like:

  • new SelendroidCapabilities( ... ): This requests an app for the test session without any preference about emulator or hardware device.
  • SelendroidCapabilities.emulator( ... ): This requests an emulator and will fail the test session if no emulator is available.
  • SelendroidCapabilities.device( ... ) This requests a hardware device and will fail the test session if no device is plugged in.
  • ... ) This starts a mobile web testing session.

The SelendroidCapabilities are only available for Java projects. For other programming languages use the following properties in the DesiredCapabilities of the Selenium client apis:

For testing native or hybrid apps:
Specify the app id of the app under test (aut). E.g. io.selendroid.testapp:0.17.0. If the version of the aut is not specified, then the latest version is assumed.
For testing Mobile Web:
Value must be android to start the 'Android driver webview app'.

Please note that either aut or browserName can be used for a test session.

Optional properties in the desired capabilities

If True, an emulator will be requested. If False, a hardware device will be requested.
Specify the Android target API version of the device. E.g. for KitKat it is: 19
Specify the locale of an emulator to be used in the test session. During the start the locale will be automatically configured. E.g. de_CH
Specify the screen size of the device: e.g. 720x1280
Specify the display number that is used to start the emulator on. Supported only in Linux platforms. E.g. 1
Specify a list of adb commands that will be executed on the target device before selendroid-server will be started. E.g. shell setprop name selendroid, please note that the adb command itself and the serial will be added by selendroid automatically.
Specify the model (e.g. Nexus One, Nexus 7, Galaxy S3) of an emulator when selecting a device.
Specify the api library you need on your device. (e.g. google) if you need a device that has Google APIs.


Selendroid supports testing on hardware devices as well as using Android emulators. In the capabilities the properties are used to find the device for the test execution. The supported properties in the capabilities are listed here.

Example for selecting a device

For running a test on the Android target platform 18 and on an emulator which is simulating a Nexus 7, the capabilities for the selendroid-test-app are:

SelendroidCapabilities capa = new SelendroidCapabilities("io.selendroid.testapp:0.8.0");
capa.setModel("Nexus 7");

Using Emulators

Selendroid can start and stop Android Virtual Devices (Avd). It cannot create new emulators, they must be created manually by the tester. After an emulator has been created, we recommend the first start be done manually in order to be sure everything works as expected.

When creating avds, please read the following configuration recommendations:

  • Whenever possible, use the Intel x86 ABI
  • Install Intel x86 Emulator Accelerator on Mac and Windows and use KVM on Linux to enable hardware acceleration to massively speed up the Emulator
  • Use at least 1024MB of RAM per emulator
  • Use at least 32MB of VM Heap per emulator
  • Configure the hardware keyboard to be used: hw.keyboard=yes
  • Use the Host GPU. If only a black screen is displayed, please deactivate this option.
  • The number of emulators you can run in parallel per machine depends heavily on the hardware of the machine you use.

Using Hardware Devices

  • Please make sure the device has no screen lock configured.
  • Devices must be plugged in via USB to the computer that the selendroid-standalone component is running on.