Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 23 Next »

Plugin Information

View Android Emulator on the plugin site for more information.

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


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 Hudson 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.


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

If you only wish to run pre-existing emulator instances (aka Android Virtual Devices, or AVDs), there are no further requirements — only the basic SDK tools 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 basic tools; you have to separately download each individual platform version you wish to build or test against.
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".


System configuration

On the Hudson 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:


Job configuration

If you have build slaves running headless, it is recommended to take advantage of Hudson's Xvnc Plugin.
With this plugin enabled, you can run any number of Android emulators in parallel on a headless slave. The Android Emulator plugin has been designed to ensure it always runs after an Xvnc server has been started.

In addition, while the Android Emulator plugin requires the Port Allocator Plugin, there is no job configuration required for this; everything is handled automatically.

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 the six named screen resolutions: 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:

  • The Google APIs add-on, based on an Android 1.6 emulator: Google Inc.:Google APIs:4
  • The Samsung GALAXY Tab add-on, based on an Android 2.2 emulator: Samsung Electronics Co., Ltd.:GALAXY Tab Addon:8

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 Hudson 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 Hudson which combinations of the matrix axes are valid. In the case of screen densities and resolutions, a configuration like this should instruct Hudson 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.

Build execution


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

Variable name

Example value




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



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



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



Name of the AVD running for the build



Locale of the AVD



OS version of the running AVD



Screen density in dpi of the AVD



Screen resolution, named or dimension, of the AVD



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, on the command line, installation is done with a command like: adb -e install -r my-app.apk.
However, as there may be multiple emulators running on one slave simultaneously, you cannot rely on the "-e" parameter of adb to specify we want to install on an emulator; you must be more specific.

For this purpose, each build with the Android Emulator plugin includes an ANDROID_AVD_DEVICE environment variable. This can be used from your Hudson, Ant or any other script as follows:
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:
adb -s $ANDROID_AVD_DEVICE shell am instrument -r -w com.example.tests/android.test.InstrumentationTestRunner | tee test-result.txt


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 Hudson is running as a Windows service, using the "Local System" account (see JENKINS-7355).

  • Workaround: configure the Hudson service to "run as" a real user

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).

  • This is caused by the ADB process crashing; the version of ADB that was due to be in SDK Tools r8 seems more stable, so this problem may be mitigated somewhat
  • Minor improvements to the plugin's communication with ADB could be added, which may also help (though would require everyone to have SDK Tools r7 or later installed)

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.

  • Please file a report if you have a generally-reproducible problem of this nature

Potential upcoming features

  • Automatic locking of AVDs per-slave, so two jobs can't try (and fail) to use the same AVD at once
  • Option to set more hardware properties (camera size, keyboard present, RAM etc.)
  • New feature requests can be placed under the 'android-emulator' component of Hudson's JIRA

Source code

The latest source code can be found on GitHub:

Version history

Version 1.6 (Dec 26, 2010)

  • Added ability to set arbitrary command line options when starting the emulator (see JENKINS-8125)

Version 1.5 (Dec 17, 2010)

  • Added support for Android 2.3 and the xhdpi screen density
  • Added detection to handle the new "platform-tools" directory used in SDK Tools r8
  • Added detection of when AVD creation fails due to the desired platform not being installed
  • Improved automated emulator unlocking to be more reliable, particularly on slower machines
  • Fixed bug which could cause build to hang when trying to shut-down the emulator

Version 1.4 (Sep 28, 2010)

  • Added feature to automatically unlock emulator after startup has completed (see JENKINS-7185)
  • Now tries to shut down emulator instances in a cleaner (hopefully more reliable) fashion

Version 1.3.1 (Sep 01, 2010)

  • Fixed bug that prevented custom screen resolutions from being recognised (see JENKINS-7337)
  • When verifying whether an AVD exists, ensure we check the same directory that the android tool creates AVDs in
    • It was possible in some environments (more likely Windows) that this was not the case

Version 1.3 (Jul 18, 2010)

  • Added ability to control whether AVDs have an SD card, and its size
  • Added option to reset emulator to its default state before each build
  • Added option allowing emulator UI to be hidden during a build
  • Added option to delay emulator start-up by a configurable period, e.g. to allow a VNC server to start up (see JENKINS-6912)

Version 1.2 (Jun 17, 2010)

  • Fixed crash that sometimes occurred when creating an emulator.
  • Added more logging and error handling while creating an emulator.
  • Fixed bug that would prevent emulators from starting.
  • Added support for Android 2.2.

Version 1.1 (May 18, 2010)

  • Added ability to create an AVD using platform add-ons (e.g. the Google Maps APIs)
  • Generated AVDs now include a blank SD card image (currently fixed at 16MB)

Version 1.0.3 (Apr 06, 2010)

  • Ensure correct environment variables are used when starting the emulator. Fixes a problem where the emulator may not start under the Xvnc Plugin

Version 1.0.2 (Apr 06, 2010)

  • Added environment variables with ADB identifier, ports and skin being used
  • Ensured correct skins are used for new AVDs

Version 1.0.1 (Apr 06, 2010)

  • Fix minor Java 5 compatibility issue

Version 1.0 (Apr 05, 2010)

  • Initial release
  • No labels