Clover-for-Maven 2 User's Guide

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

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

On this page:

Basic Usage

To use Clover with a Maven 2 project you only need to make small changes to settings.xml and pom.xml.

1. Set up your .m2/settings.xml by adding:
   This step is not needed if you wish to only run Clover via the pom.xml.

to tell Maven where to look for the plugin.

1. Set up your pom.xml by adding:
   pom.xml

You will need to set up your licence, as a <licenseLocation> element in your pom.xml configuration file.

1. 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. Use the following code:
   which will create a coverage report. The coverage report 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.

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

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:

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:instrument clover2:aggregate clover2:clover.

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

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: