This post presents a way to automate the testing procedure of web applications with mobile support on Android OS, using Arquillian testing platform and Jenkins CI. For the testing purposes we will use open source technologies. The relevant source code is available on my GitHub repository.
The below video shows the testing procedure in action.
Project under testing
The web application with mobile support which is going to be tested is the kitchensink-html5-mobile. This application is included in the JBoss AS Quickstarts examples and is using multiple HTML5, Mobile & JAX-RS Technologies. It is a deployable Maven 3 project to help you get your foot in the door developing HTML5 based desktop/mobile web applications with Java EE 6 on JBoss. This project is setup to allow you to create a basic Java EE 6 application using HTML5, jQuery Mobile, JAX-RS, CDI 1.0, EJB 3.1, JPA 2.0 and Bean Validation 1.0. It includes a persistence unit and some sample persistence and transaction code to help you get your feet wet with database access in enterprise Java.
Functional Tests Project
The kitchensink-html5-mobile-test project contains our functional tests and uses the Arquillian testing platform which enables the testing automation. Arquillian integrates transparently with the testing framework which is JUnit in this case. Three core aspects are needed for the execution of an Arquillian test case:
- container — the runtime environment
- deployment — the process of dispatching an artifact to a container
- archive — a packaged assembly of code, configuration and resources
The container’s configuration resides in the Arquillian XML configuration file while the deployment and the archive are defined in the Deployments file. Arquillian XML is configured to recognize the Android Emulator using some variables which are placed into the build environment from the Jenkins Android Emulator Plugin. The test case is dispatched to the container’s environment through coordination with ShrinkWrap, which is used to declaratively define a custom Java EE archive that encapsulates the test class and its dependent resources. Arquillian packages the ShrinkWrap defined archive at runtime and deploys it to the target container. It then negotiates the execution of the test methods and captures the test results using remote communication with the server. Finally, Arquillian undeploys the test archive.
The POM file contains two profiles:
- arq-jboss-managed — managed container
- arq-jboss-remote — remote container
By default the arq-jboss-remote (remote container) profile is active. An Arquillian remote container is a container whose lifecycle is NOT managed by Arquillian. In order to use the managed container profile, activate the corresponding profile in the POM file and set the default=”true” flag on the jboss-managed configuration in the Arquillian XML file instead of the jboss-remote configuration.
How it works – Important Notes
The functional test used to test our mobile web application is using the Arquillian testing platform. The whole concept is based on a remote Web Driver approach. Each WebDriver command makes a RESTful HTTP request to an Android HTTP server using JSON. The remote server delegates the request to Android WebDriver and returns a response. The Android Server APK path is configured inside the Arquillian XML configuration file.
Note that the address 127.0.0.1 on your development machine corresponds to the emulator’s own loopback interface. For this reason the WAR file produced from the Mobile Web Application build procedure, should be deployed by Arquillian on an application server whose services are using a host or IP binding address different than 127.0.0.1. During my tests I’ve setup this address to be 192.168.0.1. Check the Arquillian XML file where the corresponding configuration resides. An alternative solution is to use the special address 10.0.2.2. This address is a special alias to your host loopback interface (i.e., 127.0.0.1 on your development machine). However it is strongly recommended to avoid hardcoding the host address inside the source code.
The Jenkins Android Emulator plugin manages the emulator’s lifecycle. The plugin is using the Port Allocator plugin in order to create random ports so there isn’t any need to manage or set the ADB ports manually. In addition it exposes some environment variables during the build procedure. One of these variables is the ANDROID_SERIAL environment variable which represents the AVD Serial Id and uniquely identifies each emulator. The ANDROID_SERIAL environment variable value is propagated to Arquillian and the corresponding configuration resides inside the Arquillian XML configuration file.
In case you have build slaves which are headless (e.g. servers without a graphical user interface), you can still run an Android Emulator even although, by default, the emulator does require a graphical environment. You have to 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.
This example has been tested using:
- JBoss EAP 6.0
- Git (used vesrion 220.127.116.11)
- Jenkins CI (used version 1.512)
- Android SDK
- Maven (used Maven 3)
- JDK (used Open JDK 1.7.0)
Steps to automate the procedure on Jenkins CI
Clone the continuous-integration-of-mobile-web-applications-on-android repository and rename it to kitchensink-html5-mobile-test (it is not necessary to rename it – just the below instructions are based on that naming). In addition get the Kitchensink HTML5 Mobile Demo project by cloning the JBoss AS Quickstart repository.
Open a Web Browser and navigate to the Jenkins initial page.
Now you should see the Jenkin’s first page:
Navigate to Manage Jenkins → Configure System:
Setup the JDK and Maven:
Setup Git and Android SDK:
Download and install the Jenkins Android Emulator plugin and the Git Plugin:
Now you should see this page on the screen:
Restart Jenkins so that the changes are applied.
Create a new job on Jenkins. This job will build – produce the WAR file which corresponds to our kitchensink-html5-mobile mobile web application:
Setup the repository URL (instruct Jenkins to find the project):
Setup the Build Triggers, Build configuration. For convenience I have configured the SCM poll to be every minute but this is something that you can adjust according your desire:
Save the job’s configuration. Execute the job by clicking Build Now and verify that the WAR file was produced.
Now let’s create the job which executes our functional test using a selected AVD. As mentioned above the AVD lifecycle is managed through the Jenkins Android Emulator plugin.
Setup the repository URL:
Setup the Build Triggers, Build configuration. For convenience I have configured the SCM poll to be every minute but this is something that you can adjust according your desire. You can also tick the Build after other projects are built option and select the job which creates the WAR file.
Setup the emulator options. You can either select an existing emulator or configure a new one. In case you have build slaves which are headless (e.g. servers without a graphical user interface), you can still run an Android Emulator even although, by default, the emulator does require a graphical environment. You have to untick the “Show emulator window” configuration option in your job configuration. Obviously when executing the test on a headless build machine, it is executed much faster.
Save the job’s configuration and execute by clicking Build Now.