Friday, 3 June 2011

Separating Maven Unit & Integration Tests

1. Introduction

In this example I will show how you can perform a standard Maven build whilst keeping your unit and integration tests in separate packages.

Other techniques specify using either a naming convention or a separate module to do this.
This example allows true package separation and is self contained in a single profile so it can easily be used across projects. Alternative profiles can also be created for different types of test.

This solution lends itself well to generating code coverage metrics using Sonar and Jacoco.
http://johndobie.blogspot.com/2011/06/seperating-test-code-coverage-with.html

The first section shows what happens in the example and how to run it.
The second section explains how it works.

Update May 2012

This may me a more suitable solution for your project.
http://johndobie.blogspot.co.uk/2012/04/unit-and-integration-tests-with-maven.html
It's worth examining both solutions.

1.1 Example Structure

Here we have the typical maven structure and our new folder \src\integrationtest\java



1.2 Running the Example

The full code is hosted at google code.  Use the following commands to check it out and run it.
svn co https://designbycontract.googlecode.com/svn/trunk/failsafe
cd failsafe
mvn –Pit clean integration-test
Alternatively you can look at the Hudson build here :
https://designbycontract.ci.cloudbees.com/job/maven_with_split_tests/

1.3 Results of running the example

  • The tests in the standard maven test structure are run during the unit test phase as usual.
  • The tests in the \src\integrationtest\java directory are run during the integration test phase.
  • The integration test classes are placed in the seperate \target\integrationtest-classes directory

1.4  Isn't there an easier way?

Maven doesn’t really have a tidy way of dealing with this. Common suggestions are discussed here.

http://olemortenamundsen.wordpress.com/2009/07/22/strategies-for-separating-unit-and-integration-tests-using-maven-eclipse-idea-cobertura/

 The main ones are
  • Use \src\test package and use a separate directory or naming convention.
  • Put the integration tests in a separate module.
Maven does allow you to change the test source directories as demonstrated. The problem is that the Maven properties are immutable so you can't change them twice in the same build.

Firstly, we need to keep them at the defaults to enable our unit tests to run correctly.
<testSourceDirectory>src\test\java</testSourceDirectory>   
<testOutputDirectory>target\test-classes</testOutputDirectory> 

Secondly we need to change them as below for our integration tests to be run correctly.

<testSourceDirectory>src\integrationtest\java</testSourceDirectory>  
<testOutputDirectory>target\integrationtest-classes</testOutputDirectory>  

Unfortunately we cannot do this because the properties are immutable and cannot be both in the same build. However by using a number of different plugins and settings we can get the above scenario to work.

2. So what’s the Solution?

There are a number of discrete actions.
  • Firstly define variables for your integration test source and target directories
  • Use ant to create the output directory for the integration tests
  • Use the build helper plugin to add your test source to the compile path and copy any resources.
  • Compile the integration tests using -d to specify the path to the integration test source
  • Use the failsafe plugin to run the tests using parameters to specify the correct directories
  • Put it all in a profile so it can be used conveniently

These are shown in the lifecycle diagram below.



2.1  Define 2 Variables pointing to the integration tests

We need to define where the integration test classes are and where to compile and run them from.

<properties>
<integrationSourceDirectory>src\integrationtest</integrationSourceDirectory>
<integrationOutputDirectory>target\integrationtest-classes</integrationOutputDirectory>
</properties>

2.2  Create The Output Directory

Use the Maven antrun plugin to create the output directory \target\integrationtest-classes  
This is needed for the compiler which won't create it!

<execution>
<id>create-directory</id>
<phase>pre-integration-test</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<tasks>
<echo message="Creating Directory ${integrationOutputDirectory}"/>
<mkdir dir="${integrationOutputDirectory}" />
</tasks>
</configuration>
</execution>

2.3  Use Build Helper To Add The Test Source And Resources

First add the classes in src\integrationtest\java to the compile path

<execution>
<id>add-test-sources</id>
<phase>pre-integration-test</phase>
<goals>
<goal>add-test-source</goal>
</goals>
<configuration>
<sources>
<source>${integrationSourceDirectory}/java</source>
</sources>
</configuration>
</execution>
Copy any resources from \src\integrationtest\resource to \target\integration-classes
This is not strictly necessary to get things working but allows easy packaging if you required.

<execution>
<id>add-test-resources</id>
<phase>pre-integration-test</phase>
<goals>
<goal>add-test-resource</goal>
</goals>
<configuration>
<resources>
<resource>
<directory>${integrationSourceDirectory}/java</directory>
<targetPath>${integrationOutputDirectory}</targetPath>
</resource>
</resources>
</configuration>
</execution>


2.4. Compile The Classes Using -d to Control the location

By default your classes will be compiled to \target\classes
This forces your classes to be output to target\integrationtest-classes

<execution>
<phase>pre-integration-test</phase>
<goals>
<goal>testCompile</goal>
</goals>
<configuration>
<compilerArguments>
<d>${integrationOutputDirectory}</d>
</compilerArguments>
</configuration>
</execution>




2.5 Use Failsafe to run the tests and customise the locations

This runs all tests in \target\integrationtest-classes
The failsafe reports are put in \target\integrationtest-classes\failsafe-reports.
<testClassesDirectory>${integrationOutputDirectory}</testClassesDirectory>
<reportsDirectory>${integrationOutputDirectory}/failsafe-reports</reportsDirectory>
<test>**/*.java</test>
<additionalClasspathElements>
<additionalClasspath>${integrationSourceDirectory}/resources</additionalClasspath>
</additionalClasspathElements>


2.6 The 'IT' Profile

The implementation of this is placed in a profile ‘it'
https://designbycontract.googlecode.com/svn/trunk/failsafe/pom.xml


2.7 Wrapping Up.


This is a simple solution that can be rolled out to teams even if they are not strong in Maven.
By providing the profile, they only need to define their own paths.


2.7 Whats Next.


Check out how to add code coverage metrics usign Sonar.
http://johndobie.blogspot.com/2011/06/seperating-test-code-coverage-with.html

3 comments:

  1. Hi,
    is it possible to skip unit tests and run only integration tests? maven.test.skip=true skips all tests so it's not helpful.

    ReplyDelete
    Replies
    1. This comment has been removed by the author.

      Delete
    2. Hi, There probably is a way of doing it by playing with the configuration sections and the element.
      It's a shame that you can pass -DskipITs to skip only the integration tests. However there does not seem to be the same thing for the unit tests.
      It probably needs to be raised as a jira against the failsafe plugin.

      Delete