Arquillian Qunit Extension is is an Arquillian extension which automates the QUnit JavaScript testing. Arquillian Qunit Extension integrates transparently with the JUnit testing framework and therefore can be easily used in continuous integration environments. On this GitHub repo you can find a real example of how Arquillian Qunit Extension can be used to execute QUnit tests on Travis CI headless machines. Furthermore on this GitHub repo there is an example which depicts how Arquillian Qunit Extension can be used to test JavaScript code which uses the AngularJS JavaScript MVW framework.

Arquillian is a JBoss Community project.

You can find more information about this extension in this README file. In addition, there is a showcase which can be executed through Maven and shows how to setup your test case.

Using this extension, you have the option to deploy an archive during the QUnit test executions and/or execute one or more QUnit Test Suites in a single execution. Furthermore you can define the QUnit Test Suite execution order using the @InSequence annotation.

For example, assume that you want to execute two QUnit Test Suites (qunit-tests-ajax.html and qunit-random-tests.html) and that your QUnit tests included in these test suites perform Ajax requests to a Web Service. Apparently, you need this Web Service to be on host while the tests are executed. Arquillian can automatically perform the deployment of the Web Service to a container. In a such case your Arquillian test case will look like:

package org.jboss.arquillian.qunit.junit.ftest;

 import java.io.File;

 import org.jboss.arquillian.container.test.api.Deployment;
 import org.jboss.arquillian.container.test.api.RunAsClient;
 import org.jboss.arquillian.junit.InSequence;
 import org.jboss.arquillian.qunit.junit.QUnitRunner;
 import org.jboss.arquillian.qunit.junit.annotations.QUnitResources;
 import org.jboss.arquillian.qunit.junit.annotations.QUnitTest;
 import org.jboss.shrinkwrap.api.Archive;
 import org.jboss.shrinkwrap.api.ShrinkWrap;
 import org.jboss.shrinkwrap.api.spec.WebArchive;
 import org.junit.runner.RunWith;

 /**
  * Junit uses the QunitRunner controller as a test controller.
  *
  */
 @RunWith(QUnitRunner.class)
 @QUnitResources("src/test/resources/assets")
 public class QUnitRunnerTestCase {

     private static final String DEPLOYMENT = "src/test/resources/archives/ticket-monster.war";

     /**
      * Creates the Archive which will be finally deployed on the AS.
      *
      * @return an Archive<?>
      */
     @Deployment
     public static Archive<?> createDeployment() {
         return ShrinkWrap.createFromZipFile(WebArchive.class, new File(DEPLOYMENT));
     }

     /**
      * Execute the qunit-tests-ajax.html QUnit Test Suite.
      */
     @QUnitTest("tests/ticketmonster/qunit-tests-ajax.html")
     @InSequence(1)
     public void qunitAjaxTest() {
         // empty body - only the annotations are used
     }

     /**
      * Execute the qunit-random-tests.html QUnit Test Suite.
      */
     @QUnitTest("tests/generic/qunit-random-tests.html")
     @InSequence(2)
     public void qunitRandomTest() {
         // empty body - only the annotations are used
     }

 }

This post presents a way to automate the testing of mobile web applications on iOS, using Arquillian testing platform and Travis CI. Note that the Arquillian iOS Extension is not released on the Maven Central repository yet and its XML configuration might change in the future. The presented test is executed on iPhone simulator and multiple SDKs (5.0, 6.1). The relevant source code is available on my GitHub repository and the corresponding Travis-CI builds are shown on this page.

Why to use Travis CI?

Mac OS does not support the running of multiple iOS simulators at the same time. Travis CI runs builds in virtual machines that are snapshotted before each build and rolled back at the end of it. This offers a number of benefits:

  • Host OS is not affected by test suites
  • No state persists between runs
  • Passwordless sudo is available (so you can install dependencies using apt and so on)
  • It is possible for test suites to create databases, add RabbitMQ vhosts/users and so on

Travis-CI uses Mac OS X 10.8.2

Since Travis-CI runs builds in virtual machines and offers Mac OSX 10.8.2 environment, this means that we are able to run multiple iOS tests at the same time without worrying about any limitation.

Can I use Jenkins CI?

Of course you can run this test using Jenkins CI but as explained, you will have to cope with the limitation of running one iOS simulator at the same time.  The below video shows the test execution on Jenkins CI.

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 Test project

The Kitchensink HTML5 Mobile iOS Functional Test defines the three core aspects 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.

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-managed (managed container) profile is active. An Arquillian managed container is a container whose lifecycle is managed by Arquillian. In order to use the remote container profile, activate the corresponding profile in the POM file and set the default=”true” flag on the jboss-remote configuration in the Arquillian XML file. Set the flag to false for the jboss-managed configuration as well.

The configuration regarding the iOS simulator resides inside the POM and the system properties are propagated to the Arquillian XML. As mentioned in the Arquillian iOS Extension README, the Arquillian iOS extension’s configuration inside the Arquillian XML, might change in the future.

<!-- Value should be iphone or ipad -->
<property>
    <name>arq.ios.family</name>
    <value>iphone</value>
</property>
<!-- SDK version -->
<property>
    <name>arq.ios.sdk</name>
    <value>6.0</value>
</property>
<!-- local copy of Selenium SVN repository -->
<property>
    <name>arq.ios.drone.localSeleniumCopy</name>
    <value>/Users/jboss/Workspace/selenium-read-only</value>
</property>
<property>
    <name>arq.webdriver.remote.address</name>
    <value>http://localhost:3001/wd/hub</value>
</property>
<property>
    <name>arq.webdriver.remote</name>
    <value>true</value>
</property>

For convenience reasons, the mobile application’s WAR is included in the project. You can find it inside the assets folder.

Development approach / methodologies

The development approach is driven from the desire to decouple the testing algorithmic steps / scenarios from the implementation which is tied to a specific DOM structure. For that reason the Page Objects and Page Fragments patterns are used. The Page Objects pattern is used to encapsulate the tested page’s structure into one class which contains all the page’s parts together with all methods which you will find useful while testing it. The Page Fragments pattern encapsulates parts of the tested page into reusable pieces across all your tests.

Functional test execution

Before executing the functional test you have to install the Arquillian iOS Extension. Since this artifact is not available from the Maven Central Repository yet, you have to install it in your Maven repository manually.

Clone the repository and execute:

mvn install

The execution of the functional test is done through maven:

mvn test

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 1.8.1.4)
  • 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:

jenkins_1

Navigate to Manage Jenkins → Configure System:

jenkins_2

Setup the JDK and Maven:

jenkins_3

Setup Git and Android SDK:

jenkins_4

Download and install the Jenkins Android Emulator plugin and the Git Plugin:

jenkins_5

jenkins_6

Now you should see this page on the screen:

jenkins_7

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:

jenkins_8

Setup the repository URL (instruct Jenkins to find the project):

jenkins_9

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:

jenkins_10

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.

jenkins_15

Setup the repository URL:

jenkins_16

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.

jenkins_17

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.

jenkins_18

Save the job’s configuration and execute by clicking Build Now.