View Android Emulator on the plugin site for more information.
Lets you automatically generate, launch and interact with an Android emulator during a build, with the emulator logs being captured as artifacts.
Table of Contents
Problems with Android SDK Tools
Due to a regression in SDK Tools r12 and r13 (see Android bug #18444), running any builds with the "Use emulator snapshots" option enabled (which is the default), would likely fail to load in the state you expect. For example the emulator may not be ready for use, and the screen may not be unlocked.
To avoid this, either keep using r11 or earlier, or update to r14 or newer. However, if you update, you will have to manually delete all existing snapshot images and allow this plugin to re-create them.
See the Known Issues page on the Android Tools site for more information.
Similarly, snapshot support is not yet fully functioning in Android 4.0. An initial snapshot can be created, but subsequently loading from that snapshot will crash the emulator immediately.
As a workaround, you can uncheck "Use emulator snapshots" in any jobs where you are seeing problems.
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.
This plugin lets you automate a number of Android-related tasks during a build:
- Creating a new Android emulator
- Its configuration can be parameterised, including OS version, screen size, language and hardware properties
- Running any Android emulator
- Waits until the emulator is fully started-up
- Emulator snapshots can be automatically created
- This allows a very fast startup time for subsequent builds
- This ensures subsequent builds will start from the same clean state
- Logs are automatically captured and saved
- Emulator will be shut down automatically when the build has finished
- Multiple instances of the same emulator are automatically prevented from running concurrently
- Installing an Android package onto an emulator
- Uninstalling an Android package from an emulator
- Running the
- Parsing output from running
- The build outcome can be automatically marked as unstable or failed in case a crash is detected
Automated installation of the Android SDK should be possible in future, meaning build machines could more easily be deployed without manual intervention.
Please see the upcoming features section for how you can support this, or the running on Amazon EC2 section for a rough guide to automating setup for this plugin.
Jenkins version 1.377 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.
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:
- SDK Tools
- SDK Platform-tools
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".
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.
Running on headless build machines
If you have build slaves which are headless (e.g. Linux servers that don't have a graphical user interface), you can still run an Android Emulator even although — by default — the emulator does require a graphical environment.
Just untick the "Show emulator window" configuration option in your job configuration. This is the equivalent of using the emulator's "
-no-window" command-line option.
Using an artificial graphical environment
It is also possible to run the Android emulator UI on a headless build slave by making use of an articifial X server, such as Xvnc.
In this case, a recommended setup is to install both Xvnc and the Xvnc Plugin for Jenkins. With this plugin enabled in your job — and Xvnc configured to run without requesting a password — 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.
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
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.
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 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:
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.
For convenience, the plugin places a number of variables into the build environment relating to the emulator in use:
Identifier for connecting to this AVD, e.g.
Identifier for connecting to this AVD, e.g.
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.
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.
Since version 1.15, the
ANDROID_SERIAL environment variable has been automatically set by the plugin. Because the
adb tool automatically uses this variable to determine which Android device to communicate with, you no longer need to pass in parameters like "
-s" or "
Basically, whenever you want to call
adb as part of your job, just call
adb as you normally would.
The sections below are left for reference for users who are using version 1.14 or older.
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:
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
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
Installing and uninstalling APKs
Since version 1.9, the plugin can automatically install an APK on the started emulator for you.
Under the "Build" section of your job configuration, select "Add build step" and choose "Install Android package".
In the "APK file" field that appears, enter the filename of the APK you wish to install. When the job runs, the APK will be automatically installed after the emulator has started up.
Note: It is also possible to use this build step without having started an emulator via this plugin — you can install an APK on an attached device or other emulator.
Running the Android
The plugin provides a Build Step called "Run Android monkey tester" which will run the monkey stress-testing tool against the given Android package.
The output is saved to a file — by default "
monkey.txt" in the root of the build workspace.
Also provided is a method of parsing the output of the monkey testing tool.
Given a filename — defaulting to "
monkey.txt" in the root of the build workspace — the plugin will parse the output and display the result on the build page.
Optionally, if the monkey output reveals your Android application crashed or caused an "Application Not Responding" situation, the build can be marked as UNSTABLE or FAILURE.
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
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).
- Workaround: configure the Jenkins 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
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
- If your slave is running Linux, you may be running into Android bug #17294
In this case, there is a workaround assuming your build doesn't need to use the emulator's audio input:
- Add a custom hardware property called "
hw.audioInput" with the value "
- Add a custom hardware property called "
Potential upcoming features
Automated installation of the Android SDK
It should be possible to automatically install the Android SDK and the correct dependencies on any Jenkins node, without manual intervention.
This feature is already quite complete (source is on the auto-install branch), so the curious can try this out already.
However, because the SDK Tools currently lack a way of automatically installing only certain SDK components, the plugin will download every Android platform version — a total of around 1GB. Auto installation is also currently not available on Windows.
To help this feature be completed, please add a "star" to support these Android feature requests:
- New build step that automates the execution of the default Android test runner
- New feature requests can be placed under the 'android-emulator' component of Jenkins JIRA
The latest source code can be found on GitHub:
Version 1.18 (September 12, 2011)
- Fixed bug introduced by Android SDK Tools r12, where emulator startup was not detected properly on Windows (JENKINS-10815)
- Fixed bug where build would get stuck during emulator startup if
- Thanks to Jørgen Tjernø
- Fixed bug where logcat processes were not always killed at the end of a build (JENKINS-10785)
- Made emulator shutdown more robust and prevent builds from hanging if the emulator is unresponsive (JENKINS-10778)
- Thanks for Richard Mortimer for the investigation and fixes
Version 1.17 (August 25, 2011)
- Added ability to use variables when specifying the package ID to run monkey against
- Minor monkey fixes and improvements
Version 1.16 (August 19, 2011)
- Added support for Android 3.2
- Added ability to specify the psuedo-random seed value used when running monkey (including random and time-based values)
- Thanks to Jan Berkel
- Stopped redundant logcat output from being included for each build when using snapshots (JENKINS-9831)
- Changed startup behaviour to allow manual management of snapshots while the emulator is running (JENKINS-10422)
Version 1.15 (May 20, 2011)
- Added support for Android 3.1
- Export ANDROID_SERIAL environment variable, making it easier to use
- Fixed bug where an APK with spaces in its filename could not be installed (JENKINS-9700)
- Fixed regression in config UI, where checkbox states weren't shown properly (JENKINS-9747)
Version 1.14 (May 13, 2011)
- Added logic to ensure multiple builds which need the same AVD will not run in parallel on the same machine (see JENKINS-7353)
- Thanks to Kohsuke Kawaguchi and Andrew Bayer for the assistance
- Added new build step that runs the monkey testing tool on an emulator or device
- Added a result publisher that parses monkey tool output, publishes a summary on the build page and updates the build result accordingly
Version 1.13 (Apr 20, 2011)
- Fixed bug where snapshots would not function with "Show window" disabled (see JENKINS-9462)
- Thanks to Valdis Rigdon
Version 1.12 (Apr 08, 2011)
- Fixed bug which caused creation of a brand new emulator to fail if snapshots were enabled
Version 1.11 (Apr 07, 2011)
- Added automated reconnection of the emulator to ADB during startup, in case ADB crashes (see JENKINS-7693)
- Now connects to ADB in the same way that manually-started emulators do, potentially also improving stability
Version 1.10 (Apr 04, 2011)
- Added automated support for emulator snapshots (added in SDK Tools r9), which enables much faster start-up times
- Fixed bug which could prevent jobs from starting when SDK Tools version r7 or older was installed
Version 1.9 (Mar 06, 2011)
- Added new build step that can install an APK on an emulator or device
- Added new build step that can uninstall an APK from an emulator or device
Version 1.8.1 (Feb 23, 2011)
- Added support for Android 3.0, including WXGA resolution (1280x800) and new locales
Version 1.8 (Feb 21, 2011)
- Added ability to set custom hardware properties such as device RAM, Dalvik heap size, keyboard present etc. (see JENKINS-8124)
Version 1.7 (Feb 09, 2011)
- Added support for Android 2.3.3
- Improve detection of failures during startup, plus improved logging and minor cleanups
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
androidtool 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