{hudson-plugin-info:pluginId=android-emulator|src=github}

Lets you automatically generate and run an Android emulator for the duration of a build, with the emulator logs being captured as artifacts.

Description

In order to provide effective test coverage of the ever-increasing range of Android platform versions, screen resolutions and densities (amongst other device properties), automated and scalable build tools like Jenkins become highly advantageous.

This plugin aims to vastly simplify automated testing of Android applications across a wide range of virtual devices by automatically generating emulator instances, starting up those emulators and capturing the logging output, with many device parameters being under your control.

Requirements

Jenkins

Jenkins version 1.340 or newer is required.
Since this version was released well before the Hudson/Jenkins split, this plugin can also be used with Hudson. Any changes to this will be posted here and on the Hudson wiki.

Android

A copy of the Android SDK must be available on each Jenkins node you wish to test on.

With the SDK installed, you must install at least two further components, via the Android SDK and AVD Manager:

If you only wish to run pre-existing emulator instances (aka Android Virtual Devices, or AVDs), there are no further requirements — only these items are required.

If you want the plugin to automatically generate new emulator instances, you must install one or more Android platform versions into the SDK.
By default, the SDK only comes with the bare minimum; you have to separately download each individual platform version you wish to build or test against.

Again, this is done via the Android SDK and AVD Manager tool, accessible via the command line "android", or via the "Window" menu in Eclipse, if you use the Eclipse ADT plugin. From the SDK Manager, you can easily install the desired "SDK Packages".

Configuration

System configuration

On the Jenkins master, you can optionally specify the location where each build node can locate a copy of the Android SDK.

This can either be an absolute path, or can contain environment variables in the format $VARIABLE_NAME. This will be replaced at build time from the node's environment variables (see the "Node Properties" settings for each slave), or from the build's environment.

If no value is entered, or the plugin cannot find a valid SDK under the configured path, it will search under the following environment variables on the build node to try and locate a usable SDK:

If nothing is found, the plugin will search on the PATH to attempt to locate a usable set of SDK tools. If, after all these steps, the required Android SDK tools are not found, the job will be marked as failed and will stop.

Job configuration

Running on headless slaves

If you have build slaves running headless (e.g. Linux servers that don't run an X server), it is recommended to take advantage of Jenkins' Xvnc Plugin.
With this plugin enabled, you can run multiple Android emulators in parallel on a headless slave, while keeping the "Show emulator window" option enabled.

Although the Android Emulator plugin has been designed to ensure it always runs after an Xvnc server has been started, the Xvnc plugin does not wait for the Xvnc server to be fully up-and-running before handing control over to the Android Emulator plugin.

For this reason, you may want to delay emulator startup by a few seconds (e.g. three to five), giving the Xvnc server time to finish starting-up before attempting to launch an Android emulator into it. To do so, enter the desired number of seconds in the "Startup delay" field under "Advanced" options.

Other requirements

In addition, while the Android Emulator plugin requires the Port Allocator Plugin, there is no job configuration required for this; everything is handled automatically — you need not select the "Assign unique TCP ports" checkbox in the job config.

Selecting an emulator

After ticking "Run an Android emulator during build", you will be asked whether you want to run an existing AVD, or whether you want to create a new one on-the-fly with certain properties.

Using an existing emulator for a job just requires that you enter the name of the AVD you want to be started. This AVD must exist on each build node the job will be executed on. Existing AVDs are found in your $HOME/.android/avd directory and can be listed using the "android list avd" command.
As with all other properties, you can enter environment variables here using the format $VARIABLE_NAME.

Alternatively, if you don't have a particular AVD accessible on each build node, the plugin can automatically generate a new emulator if one doesn't already exist:

Each property is mandatory, aside from the device locale. If this is not entered, the Android emulator default locale of US English (en_US) will be used when starting the emulator.

Each field will auto-complete with the default Android SDK values, i.e 120, 160, 240dpi densities and named screen resolutions including: QVGA, WQVGA, FWQVGA, HVGA, WVGA, FWVGA. However, you can enter your own values if you wish to use a custom OS image, screen density, resolution or locale.
Screen resolutions can be entered either using the named values, or as a "width times height" dimension, e.g. 480x800.

Using Google Maps and other SDK add-ons

As mentioned above, the "Android OS version" field will auto-complete to existing SDK versions such as "1.5" or "2.2".

However, it is possible to enter different values in this field, for example if you want to use an Android SDK add-on that you have installed, e.g. the Google APIs add-on or the Samsung GALAXY Tab add-on.

In these cases, just enter the appropriate value given by the "android list target" command. For example:

Multi-configuration (matrix) job

The real awesomeness of this plugin comes when used in conjunction with a multi-configuration job type.

By using the "Run emulator with properties" setting, in conjunction with one-or-more matrix axes and the Android Emulator plugin's variable expansion, you can generate and test with a large number of distinct Android emulator configurations with very little effort.

To give a full example, if you want to test your application across multiple Android OS versions, multiple screen densities, multiple screen resolutions and for several target locales, you might set up your matrix axes as follows:

As each of these axis names (i.e. "density", "locale", "os", "resolution") are exported by Jenkins as environment variables, you can make use of these when launching a new Android emulator:


When the build executes, this would automatically generate and allow you to test your application against 64 unique device configurations.

However, you should note that not all combinations are valid. For example, a WVGA (800x480) resolution device makes no sense with a screen density of 120 (unless you have superhuman eyesight).

For this purpose, you can use the "Combination Filter" feature, which tells Jenkins which combinations of the matrix axes are valid. In the case of screen densities and resolutions, a configuration like this should instruct Jenkins to only build for configurations which make sense:

(density=="120").implies(resolution=="QVGA" || resolution=="WQVGA" || resolution=="FWQVGA") &&
(density=="160").implies(resolution=="HVGA" || resolution=="WVGA" || resolution=="FWVGA") &&
(density=="240").implies(resolution=="WVGA" || resolution=="FWVGA")

Note that each variable refers to one of the matrix axes, not an Android Emulator plugin property.

Running on Amazon EC2

Using the Amazon EC2 Plugin for Jenkins, you can automatically launch build slaves on demand.

Here is a basic "Init script" that can be used in conjunction with a Ubuntu-based EC2 image, such as those listed on alestic.com. In this case, a 64-bit version of Ubuntu 10.04 LTS was used (e.g. ami-631f2b17), with Java and Android being automatically installed and configured when the machine starts up.

# Add Java repository to package sources
sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
sudo apt-get update

# Upgrade existing packages
sudo apt-get -y upgrade

# Mark the the "Distributor License for Java" as accepted
echo sun-java6-jdk shared/accepted-sun-dlj-v1-1 select true | sudo /usr/bin/debconf-set-selections

# Install the JDK and required x86 libraries
sudo apt-get install -y sun-java6-jdk ia32-libs

# Retrieve and extract Android SDK
wget http://dl.google.com/android/android-sdk_r09-linux_x86.tgz
tar -zxf android-sdk_r09-linux_x86.tgz
mv android-sdk-linux_x86/ /home/ubuntu/android

# Export environment variables and put Android tools on the path
export ANDROID_HOME=/home/ubuntu/android
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

# Download and install the SDK tools and all available Android platforms
/home/ubuntu/android/tools/android update sdk -u -t platform,platform-tool,tool

# Done!

Build execution

Environment

For convenience, the plugin places a number of variables into the build environment relating to the emulator in use:

Variable name

Example value

Description

ANDROID_AVD_DEVICE

localhost:34564

Identifier for connecting to this AVD, e.g. adb -s localhost:34564 shell

ANDROID_AVD_ADB_PORT

34564

Port used by ADB to communicate with the AVD (random for each build)

ANDROID_AVD_USER_PORT

40960

Port used to access the AVD's telnet user interface (random for each build)

ANDROID_AVD_NAME

hudson_en-GB_160_HVGA_android-7

Name of the AVD running for the build

ANDROID_AVD_LOCALE

en_GB

Locale of the AVD

ANDROID_AVD_OS

2.1

OS version of the running AVD

ANDROID_AVD_DENSITY

160

Screen density in dpi of the AVD

ANDROID_AVD_RESOLUTION

HVGA

Screen resolution, named or dimension, of the AVD

ANDROID_AVD_SKIN

HVGA

Skin being used by the AVD, e.g. WQVGA432 or 480x800

Using the emulator

Now that you have an Android emulator running, you'll probably want to install one or more Android applications (APKs) and start running some tests.

Normally, when running an Android application using Eclipse or the command line, either your APK is automatically installed (because there is only one emulator/device attached to your PC), or Eclipse allows you to choose from a list. Similarly, when building from the command line, installation is done with a command like: "adb -e install -r my-app.apk", where "-e" specifies the emulator (or "-d" a USB-attached device).

However, as Jenkins may be running multiple Android-related builds at once, with several emulators running in parallel, it's not possible to automatically determine which emulator should be used. Nor can the user be prompted at build time.

For this reason, each build with the Android Emulator plugin includes an ANDROID_AVD_DEVICE environment variable, among others shown in the table above.

You must instruct your build to use this information to select the correct emulator, as the following sections indicate.

Using Android's default Ant build system

The default build system for Android is Apache Ant, which is well supported by Jenkins.

When calling targets like "ant install" or "ant run-tests", the Android build system allows you to use the adb.device.arg property to specify where the application should be installed to.

To make use of this in an "Invoke Ant" build step, just add the following to your Ant "Properties" section:
adb.device.arg="-s $ANDROID_AVD_DEVICE"

Using shell commands

If you aren't using Ant, but want Jenkins to run adb commands for you via an "Execute shell" build step, the process is similar.

To install, use the ANDROID_AVD_DEVICE environment variable with the -s flag:
adb -s $ANDROID_AVD_DEVICE install -r my-app.apk

This would be automatically expanded by the shell to something like:
adb -s localhost:34564 install -r my-app.apk

The same principle applies for any other adb commands you wish to perform, for example to start running tests:
adb -s $ANDROID_AVD_DEVICE shell am instrument -r -w com.example.tests/android.test.InstrumentationTestRunner | tee test-result.txt

Artifacts

The full emulator log is captured for the complete duration of a build. This corresponds to the output of "adb logcat -v time", i.e. the main log output including timestamps.
This will be archived automatically as a build artifact, with the name logcat.txt.

Known issues

Running in a Windows service as "Local System"

New AVDs cannot be generated and run if Jenkins is running as a Windows service, using the "Local System" account (see JENKINS-7355).

Unexpected timeouts or hanging during build

AVDs can, on occasion, time-out unexpectedly or stop responding during a build, e.g. when trying to install an APK (see JENKINS-7354).

AVDs may not shut down fully at the end of a build

Sometimes the emulator process does not shut down fully at the end of a build (requiring a kill -9 on Linux); the plugin sends a console command to terminate the emulator and the UI window closes, but the actual emulator process does not die.

Potential upcoming features

Source code

The latest source code can be found on GitHub:
https://github.com/jenkinsci/android-emulator-plugin

Version history

Version 1.7 (Feb 09, 2011)

Version 1.6 (Dec 26, 2010)

Version 1.5 (Dec 17, 2010)

Version 1.4 (Sep 28, 2010)

Version 1.3.1 (Sep 01, 2010)

Version 1.3 (Jul 18, 2010)

Version 1.2 (Jun 17, 2010)

Version 1.1 (May 18, 2010)

Version 1.0.3 (Apr 06, 2010)

Version 1.0.2 (Apr 06, 2010)

Version 1.0.1 (Apr 06, 2010)

Version 1.0 (Apr 05, 2010)