Clover-for-Maven 2 and 3 User's Guide

The Maven 2 and 3 Clover plugin produces Clover reports from Maven 2 and 3 projects.

Test Optimization for Maven 2 and 3
To get started using Test Optimization, follow the instructions for Using Test Optimization with Clover-for-Maven 2 and 3.

Maven Site Docs
For documentation presented in the standard Maven format, see the Maven Site Docs.

On this page:

Basic Usage

The quickest and easiest way to try Clover is from the command line, for example:

1. Set up your pom.xmlby adding:

   pom.xml

   Either change ${clover.version} to the current Clover version, or define a property in your pom.xml that sets this value.
   
   Clover ships with a 30 day evaluation license. After 30 days you need a valid Clover license file to run Clover. You can obtain a free 30 day evaluation license or purchase a commercial license at http://my.atlassian.com. You will need to set up your licence, as a <licenseLocation> element in your pom.xml configuration file.

2. Now, simply invoke Clover with Maven on the command line. This will instrument your sources, build your project, run your tests and create a Clover coverage database.

You can also have Clover run as part of your build. Learn how.

There are three basic parts executed when recording code coverage with Clover.

1. The clover2:setup goal will instrument your Java source files.
2. The test phase is Maven 2 and 3's standard command for running a unit test phase.
3. The clover2:clover goal generates an HTML, XML, PDF or JSON report.

The command clover2:aggregate goal is used for merging coverage data generated by multi-module projects.

Hence, if you use the following code:

This will create a coverage report, which will be created in this directory:

Clover should now be fully set up for basic operation.

For more license configuration options, see the FAQ pages.

Checking a Coverage Goal

You can check that your test coverage has reached a certain threshold, and fail the build if it has not by adding a targetPercentage tag to your plugin configuration in pom.xml:

You can then use the clover2:check target to examine the Clover database and check that you have reached the coverage threshold.

If you want the build to succeed anyway (printing a warning to your log), use the command line option -DfailOnViolation=false.

Ratcheting Up Coverage

Clover can be configured to fail the build or warn you when the code coverage for a project drops relative to the previous build.

The steps to configure the maven-clover2-plugin to do this are as follows:

• specify the clover2:historyDir configuration for clover2:check
• save a history point using the clover2:save-history goal at report time. This will be used by the subsequent build.

You can also optionally specify a historyThreshold parameter which is the leeway used by clover2:check when comparing the coverage with the previous build. 

Configuring the Plugin

Controlling which Source Files are Instrumented

Use configuration elements to exclude and include source files from being instrumented:

Excluding your Tests from Instrumentation

If you don't want to instrument your test classes, add the following to your pom.xml (note that this disables the reporting of per-test coverage):

Controlling the level of Instrumentation

You can define the level that Clover will instrument to (and the respective performance overhead). Valid values are 'method' level (low overhead) or 'statement' level (high overhead). The default setting is 'statement'.

Setting this to 'method' greatly reduces the performance overhead of running Clover, however limited or no reporting is
available as a result. The typical use of the method setting is for Test Optimization only.

To set this value in your pom.xml:

To set this value on the Maven command line:

The setting above will result in method level only instrumentation; no statement level coverage will be available.

Configuring Contexts

Clover allows you to exclude coverage contexts from the coverage report.

To exclude try bodies and static initialiser blocks:

To exclude arbitrary statements or methods you can specify one or more custom contexts like so:

*NB: A method context regexp must match the entire method signature. A statement context regexp must match the full statement, including the ';'.

Each one still needs to be 'enabled' via the <contextFilters/> element:

If you are filtering code from your coverage reports, you can keep track of what is filtered using the custom filteredElements column. See Creating custom reports for more information.

Setting JDK Level

In most cases Clover will autodetect the JDK you are using. If you are building with a 1.5 JDK but have set the maven-compiler-plugin's source and target parameters to use a JDK version of 1.4 you will need to set the Clover JDK level to 1.4:

Setting a Clover Flush Policy

You can set the Clover Flush Policy and interval:

Choosing Report Formats

The clover2:clover target generates an HTML report by default. You can use the generateHtml, generatePdf and generateXml configuration elements to choose which report formats should be produced:

Setting the Clover DB Location

To specify a particular location for your Clover Database:

and to set a location for the merged database:

Do not set these locations explicitly if you have a multi-module project.

Getting Information about your Clover Database

The clover2:log goal will summarize your Clover database.

Generating Historical Reports

To include the generation of historical reports in your Clover reports, add the generateHistorical element to your Clover plugin configuration:

That will include your historical savepoints, if any, in the generated report.

To generate a savepoint, run the clover2:save-history goal.

To avoid having mvn clean remove your savepoints you should set the location of the history directory, which defaults to $project.build.directory/clover/history:

Creating Custom Reports

It is now possible to define an external clover report descriptor file, the same way one can define a site.xml descriptor file. The descriptor file is basically a stripped down Ant file which will be run to produce the reports. All options available in clover-report can be specified.

The default report descriptor used by the maven-clover2-plugin is:

This is a very simple Ant file, which defines two known targets: "historical" and "current" .
If there are no history points saved (via: clover2:save-history) then only the "current" target will be called. Otherwise, the "historical" target gets called which generates both a historical and current report which are linked together.

To change Clover's default reporting behavior, it is easiest to copy this file and add the changes you require. For a full list of clover-report elements and attributes, please consult the clover-report documentation.

This file can be stored either on your local file system, or in your maven repository as a classified artifact.

If stored on the file system, set this system property:

or specify this element:

in the <configuration> element for the maven-clover2-plugin in your pom.xml.

If you wish to keep this descriptor in your maven repository you must specify this system property:

or set this element:

in the <configuration> element for the maven-clover2-plugin in your pom.xml.
The descriptor should be deployed using the "clover-report" classifier. For example:

Properties for Custom Reports

A custom clover report descriptor can now access the standard Maven 2 and 3 properties.

The following properties are available:

• project.url
• project.version
• project.name
• project.description
• project.id
• project.groupId
• project.inceptionYear

In addition to these properties, any additional properties defined in pom.xml will also be available.

Working with Multimodule Projects

You can use the clover2:aggregate goal to combine the Clover databases of child projects into a single database at the parent project level.

Because of this Maven bug, aggregation of databases occurs before the child databases have been generated, when you use the site target.

You can create Clover reports for a multimodule project with the command line mvn clover2:setup test clover2:aggregate clover2:clover.

Per-test coverage reporting is supported in Clover 2.1 onwards.

Configuring the GMaven Plugin for Groovy Support in Maven 2 and 3

If you are using Clover-for-Maven 2 and 3 on Groovy code, you would typically need to define a plugin element for the GMaven Plugin in your pom.xml file.

As shown in the example definition below, the GMaven Plugin definition requires the Groovy dependency (groovy-all). However, within this dependency, you must define a version of Groovy that Clover supports inside a version sub-element. The following example GMaven Plugin definition uses Groovy 1.6.2, which is the earliest version of Groovy that Clover supports.

If you omit this version element, the GMaven Plugin will default to using Groovy version 1.6.0, which is not compatible with Clover.

If you use cross-compilation with Groovy code, please refer to the Cross Compilation using Groovy on the Clover for Maven 2 and 3 Best Practices page.

Running Goals via pom.xml

The goals described above can be executed by specifying them in your pom.xml.

To generate a Clover report when you run the site goal:

To instrument your sources whenever you build:

To include aggregation of child modules:

Using Test Optimization

Once your build has Clover integrated, you can move on to Using Test Optimization with Clover-for-Maven 2 and 3. Test Optimization saves valuable time in the build and test cycle, by only running tests that cover code which has changed since the last build.

Run Clover Without Editing the pom.xml

It is possible to run the maven-clover2-plugin entirely from the command line, without the need to modify your pom.xml.

To do so, set up your .m2/settings.xml by adding:

to tell Maven where to look for the plugin.

This step is not needed if you wish to only run Clover via the pom.xml.

You can then invoke Clover from the command line like so:

The Clover 2 'instrument' goal (clover2:instrument) can be used if you need to actually deploy a project's artifact to production and have clover run at the same time. This will fork the lifecycle and cause each Clover artifact to contain the -clover classifier.