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.
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.
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 basic SDK 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 the basic SDK tools 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 basic toolsbare minimum; you have to separately download each individual platform version you wish to build or test against.
This 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".
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 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 any number of multiple Android emulators in parallel on a headless slave. The , 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.
Each field will auto-complete with the default Android SDK values, i.e 120, 160, 240dpi densities and the six 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.
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 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 there Jenkins may be running multiple Android-related builds at once, with several 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 purposein 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. This can be used from your Jenkins, Ant or any other script as follows:
adb , 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:
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