Clover-for-Maven 2 User's Guide

The Maven 2 Clover plugin produces Clover reports from Maven 2 projects. Please report any issues in the plugin's JIRA project.

This plugin is open source, under the Apache license. Its source code is available here: http://svn.atlassian.com/svn/public/contrib/clover/maven-clover-plugin/

It is derived from the original Maven 2 plugin for Clover 1 written by Vincent Massol. The groupId has been changed from org.apache.maven.plugins to com.atlassian.maven.plugins.

The plugin does not include a built in evaluation license - you will need to download a license from Atlassian and configure its location in your pom.xml.

Basic Usage
Checking a Coverage Goal
Configuring the Plugin

Controlling which Source Files are Instrumented
Excluding your Tests from Instrumentation
Configuring Contexts
Setting JDK Level
Setting a Clover Flush Policy
Choosing Report Formats
Setting the Clover DB Location

Getting Information about your Clover Database
Generating Historical Reports
Working with Multimodule Projects
Running Goals via pom.xml

Basic Usage

To use Clover 2.1 with a Maven 2 project you need to:

Set up your .m2/settings.xml by adding:

.m2/settings.xml

...
<pluginGroups>
    <pluginGroup>com.atlassian.maven.plugins</pluginGroup>
</pluginGroups>
...
<profiles>
  <profile>
    <id>myprofile</id>
    <activation>
      <activeByDefault>true</activeByDefault>
    </activation>
    ...
    <pluginRepositories>
      <pluginRepository>
        <id>atlassian-m2-repository</id>
        <name>Atlassian Maven 2.x Repository</name>
        <url>http://repository.atlassian.com/maven2</url>
      </pluginRepository>
    </pluginRepositories>
    ...
  </profile>
</profiles>

to tell Maven where to look for the plugin, and

.m2/settings.xml

<profiles>
    ...
    <profile>
      <id>myprofile</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      ...
      <properties>
        <clover.licenseLocation>...path to your Clover license file...</clover.licenseLocation>
      </properties>
      ...
   </profile>
   ...
</profiles>

to set a license location property which you can refer to from all your poms.
You then need to configure the plugin in your pom.xml:

pom.xml

<build>
    <plugins>
        ...
        <plugin>
            <artifactId>maven-clover-plugin</artifactId>
            <groupId>com.atlassian.maven.plugins</groupId>
            <configuration>
                <licenseLocation>${clover.licenseLocation}</licenseLocation>
            </configuration>
        </plugin>
    </plugins>
</build>

Of course you could put the license location explicitly in the pom, rather than referring to the property.

Run the command mvn clover:instrument which will instrument your sources, build your project and run your tests, creating a Clover coverage database.
Run the command mvn clover:clover which will create a coverage report. The coverage report will be created in the target/site/clover directory.

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:

<configuration>
  ...
  <targetPercentage>75%</targetPercentage>
  ...
</configuration>

You can then use the clover: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:

<configuration>
  ...
  <includes>
    <include>...ant style glob...</include>
    <include>**/specialpackage/*.java</include>
  </includes>
  <excludes>
    <exclude>**/*Dull.java</exclude>
  </excludes>
</configuration>

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

<configuration>
  ...
  <includesTestSourceRoots>false</includesTestSourceRoots>
</configuration>

Configuring Contexts

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

To exclude try bodies and static initialiser blocks:

<configuration>
  ...
  <contextFilters>try,static</contextFilters>
</configuration>

Setting JDK Level

Clover will autodetect the JDK you are using, so if you are building with a 1.5 JDK but have set the maven-compiler-plugin to use a jdkLevel of 1.4 you will need to set the Clover JDK level to 1.4:

<configuration>
  ...
  <jdk>1.4</jdk>
</configuration>

Setting a Clover Flush Policy

You can set the Clover Flush Policy and interval:

<configuration>
  ...
  <flushPolicy>threaded</flushPolicy>
  <flushInterval>5000</flushInterval>
</configuration>

Choosing Report Formats

The clover: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:

<configuration>
  ...
  <generatePdf>true</generatePdf>
  <generateXml>true</generateXml>
  <generateHtml>false</generateHtml>
</configuration>

Setting the Clover DB Location

To specify a particular location for your Clover Database:

<configuration>
  ...
  <cloverDatabase>/foo/bar</cloverDatabase>
</configuration>

and to set a location for the merged database:

<configuration>
  ...
  <cloverMergeDatabase>/foo/bar</cloverMergeDatabase>
</configuration>

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

Getting Information about your Clover Database

The clover: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:

<configuration>
  ...
  <generateHistorical>true</generateHistorical>
</configuration>

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

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

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

<configuration>
  ...
  <historyDir>/home/me/dev/project/history</historyDir>
</configuration>

Working with Multimodule Projects

You can use the clover: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 clover:instrument clover:aggregate clover: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.xmnl.

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

<project>
  ...
  <reporting>
    <plugins>
      ...
      <plugin>
        <groupId>com.atlassian.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          ...
        </configuration>
      </plugin>
    </plugins>
  </reporting>
...

To instrument your sources whenever you build:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>com.atlassian.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          ...
        </configuration>
        <executions>
          <execution>
            <phase>pre-site</phase>
            <goals>
              <goal>instrument</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

To include aggregation of child modules:

<project>
...
  <build>
        <plugins>
            <plugin>
                ...
                <executions>
                    <execution>
                        <id>main</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>instrument</goal>
                            <goal>aggregate</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>site</id>
                        <phase>pre-site</phase>
                        <goals>
                            <goal>instrument</goal>
                            <goal>aggregate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
...