Novoda

Continuous feedback on how our changes affect the current code allow us to confidently add functionality. Documentation around testing on the Android platform continuous or otherwise is scarce so here we explain how to continuously compile your Android project’s tests in a central area for the benefit of the whole team and it’s clients.

The main components of our continuous integration system are:

Here we wish to share and document our set up and explore some capabilities of the android maven plugin. If you are brand new to it you may wish to first check out Maven in 5 minutes and maven-android-plugin’s useful Getting Started guide.

Android maven plugin helps us with the following android deployment tasks:

We want to show you a real example of an application built with the help of the maven-android-plugin. It’s an Avatar Creator app for WeeWorld.

The app is now on the market, so go ahead and check it out! (0.99$)

If you’re quite familiar with maven and the android plugin, you might want to jump straight to the Real Life Example at the end of this post and check out the full configuration.

Building your App

To buid an apk, your app first needs to cite a version of android platform as a build path dependency in your application’s pom file (as provided scope). More on dependency scope.

<dependency>
  <groupId>com.google.android</groupId>
  <artifactId>android</artifactId>
  <version>2.2.1</version>
  <scope>provided</scope>
  <type>jar</type> <!-- optional -->
</dependency>
<!--Currently valid values: 1.5_r3,1.6_r2,2.0_r1,2.0.1_r1,2.1_r1,2.2.1-->
<!--Those packages are on the maven central repository-->

The project must then reference the maven android plugin within the project’s pom along with the android API level targeted, here we cite version 2.2 (api level 8 )

<plugin>
  <groupId>com.jayway.maven.plugins.android.generation2</groupId>
  <artifactId>maven-android-plugin</artifactId>
  <configuration>
    <sdk>
      <platform>8</platform>
    </sdk>
    <deleteConflictingFiles>true</deleteConflictingFiles>
  </configuration>
  <extensions>true</extensions>
</plugin>

Reference a java compiler version, since the default source and target values are 1.3 and 1.1 respectively, and android uses annotations conforming to java 5

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <source>1.5</source>
    <target>1.5</target>
  </configuration>
</plugin>

If your project uses Any android platform plugins for instance Google maps, additional dependencies will also require referencing in the project’s pom:

<dependency>
  <groupId>com.google.android.maps</groupId>
  <artifactId>maps</artifactId>
  <version>8_r1</version>
  <type>jar</type>
</dependency>
<!-- Current versions:  3, 4_r2, 7_r1, 8_r1 -->
<!-- NOTE: those are the ones defined by goole and are  NOT in the maven
central repository and need to be installed manually with:
mvn install:install-file wih proper parepeters as decribed here:

http://maven.apache.org/plugins/maven-install-plugin/usage.html

e.g. mvn install:install-file
-Dfile=$ANDROID_HOME/add-ons/addon_google_apis_google_inc_8/libs/maps.jar
-DgroupId=com.google.android.maps -DartifactId=maps -Dversion=8_r1
-Dpackaging=jar -->

Additionally one should remember to specify the source directory if the folder structure does not follow the default maven structure:

<sourceDirectory>${project.basedir}/src</sourceDirectory>

At the same time remember NOT to specify the resource directory, as maven-android-plugin handles Android-specific resources on its own, and we don’t wnt duplicates.

This will already get your project building, but there’s much more that maven can do for You. Let’s look at some of that now.

Testing your App with an Instrumentation

You most hopefully have an accompanying instrumentation test instrumentation project for your Android application and maven can build and run these against your previously compiled project. Maven can build the test project, deploy both the app and the test, and run the instrumentation on an attached device or an emulator.

Within the instrumentation test project it will need the following dependency:

<dependency>
   <groupId>com.google.android</groupId>
  <artifactId>android-test</artifactId>
  <version>2.2.1</version>
</dependency>
<!-- Allowed values same as for android package -->
 

If it depends upon the source code of the application which it tests:

<dependency>
  <!-- optional: compile time dependency, in this case so that we can -->
  <!-- read from the R.java for example. -->
  <groupId>my.app.group</groupId>
  <artifactId>myapp</artifactId>
  <version>${project.version}</version>
  <scope>compile</scope>
  <type>jar</type>
</dependency>

Instrumentations are run through a series of interactions within a pseudo environment so you will need to specify the Device/AVD(Android virtual Device) upon which you wish to run tests:

<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>maven-android-plugin</artifactId>
  <configuration>
  <emulator>
    <avd>22</avd>
    <!-- name of the avd to deploy to and run the instrumentation on -->
    <wait>150000</wait> <!-- wait time for the emulator to start -->
    <options>-partition-size 128 -wipe-data</options>
    <!-- additional options to run the emulator with-->
  </emulator>
  <undeployBeforeDeploy>true</undeployBeforeDeploy>
</configuration>

Devices to deploy to can be specified by a serial number but generic “usb” and “emulator” values are also valid. More detailed documentation can be found here.

Instrumentation environment

Instrumentations can interact at various hook in points during the a devices connected lifecycle. Execution and binding it to a maven lifecycle phase is specified like:

<executions>
  <!-- android plugin execution that starts the emulator. -->
  <execution>
    <id>startemulator</id>
    <!-- bound to the 'initialize' phase -->
    <phase>initialize</phase>
    <goals>
      <goal>emulator-start</goal>
    </goals>
  </execution>
</executions>

The configuration above binds the android plugin’s ‘emulator-start’ goal to the ‘initialize’ phase of the maven lifecycle. This is the equivalent of manually executing mvn android:emulator-start, from a directory with a pom containing valid configuration for it. Stopping the emulator does not require this and can be run anywhere and anytime with mvn android:emulator-stop.

If we would like to stop the emulator after running the instrumentation tests, we would add the following execution:

<execution>
  <!-- android plugin execution that starts the emulator. -->
  <id>stopemulator</id>
  <!-- bound to the 'install' phase -->
  <phase>install</phase>
  <goals>
    <goal>emulator-stop</goal>
  </goals>
<execution>

Signing your release

By default, the plugin will sign the apk with the debug key. This can be disabled, producing an unsigned apk.

<configuration>
  <sign>
    <debug>false</debug>
  </sign>
<configuration>

To sign and apk with your key, we will need to use the maven-jarsigner-plugin. Although it’s a different plugin, since it’s very relevant here’s how we did it:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jarsigner-plugin</artifactId>
  <version>1.2</version>
  <executions>
    <execution>
      <id>signing</id>
      <goals>
        <goal>sign</goal>
      </goals>
      <phase>package</phase>
      <inherited>true</inherited>
      <configuration>
        <includes>
          <include>
${project.build.directory}/target/${project.artifactId}-${project.version}.apk
          </include>
        </includes>
        <keystore>${keystore.location}</keystore>
        <storepass>${keystore.password}</storepass>
        <keypass>${keystore.keypass}</keypass>
        <alias>${keystore.alias}</alias>
        <verbose>true</verbose>
      </configuration>
    </execution>
  </executions>
</plugin>

Configures the jarsigner plugin with the files (input, output), and the keystore details. Binds the plugin’s ‘sign’ goal to the ‘package’ phase of the maven lifecycle.

The ${kestore.*} variables above come from the settings.xml file, and look:

<properties>
  <keystore.location>path/to/test.keystore</keystore.location>
  <keystore.password>teststorepass</keystore.password>
  <keystore.keypass>testpass</keystore.keypass>
  <keystore.alias>testkey</keystore.alias>
</properties>

Optimization .apk files via zipalign.

The last stage of a deployment, but also very important is zipaligning the apk after it’s been signed. This aligns archived data in such a way that upon runtime memory can more efficiently store the related data. After this your apk is ready to go to the market. our configuration:

<plugin>
  <groupId>com.jayway.maven.plugins.android.generation2</groupId>
  <artifactId>maven-android-plugin</artifactId>
  <configuration>
    <zipalign>
      <verbose>true</verbose>
      <skip>false</skip><!-- defaults to true -->
      <inputApk>
    ${project.build.directory}/${project.artifactId}-${project.version}.apk
      </inputApk>
      <outputApk>
    ${project.build.directory}/${project.artifactId}_v${project.version}.apk
      </outputApk>
    </zipalign>
  </configuration>
  <executions>
    <execution>
      <id>zipalign</id>
      <phase>verify</phase>
      <goals>
        <goal>zipalign</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Configures the plugin for the zipalign goal and binds that goal the the ‘verify’ phase of the maven lifecycle.

Real Life Example

The above describes taking full control over how maven-android-plugin builds and tests your android application. In reality though, one wouldn’t really use all of the above settings in one pom. Here’s an example of a fully-configured real-life project using ALL of the above:

The project makes use of a parent-child structure and maven profiles to manage both App and Instrumentation projects and handle different cases of builds. Feel free to have a look and se how we’ve done it. For more guides and tips about android development and continuous integrations check back to our blog – we’ll have something here soon!

Topics to expect:

References:

maven-android-plugin site, the Getting Started guide and their wiki page.
Installing a specific file into a local maven repository
Signing apk files with maven
Zipalign apk files with maven-android-plugin

Other relevant and important resources:

Maven: The complete reference book and it’s Android Chapter