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.

On this page:

Basic Usage

<pluginGroups>
    <pluginGroup>com.atlassian.maven.plugins</pluginGroup>
</pluginGroups>

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

mvn clover2:setup test clover2:aggregate clover2:clover

mvn clover2:setup test clover2:aggregate clover2:clover

target/site/clover

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

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

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:

<configuration>
          <instrumentation>method</instrumentation>
      </configuration>

To set this value on the Maven command line:

-Dmaven.clover.instrumentation=method

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:

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

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

<configuration>
  <methodContexts>
    <main>(.* )?public static void main\(String\[\] argv\).*</main>
  </methodContexts>
  <statementContexts>
    <log>System.out.println\(.*\);</log>
    <iflog>if.*\(LOG\.is.*\).*</iflog> <!-- NB: must match entire statement, including any semicolons. -->
  </statementContexts>
</configuration>

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

<configuration>
  ...
  <contextFilters>main,log,iflog</contextFilters>
</configuration>

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:

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

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

<configuration>
  ...
  <generateHistorical>true</generateHistorical>
</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:

<configuration>
  ...
  <historyDir>${user.home}/history/${project.artifact}</historyDir>
</configuration>

Creating Custom Reports

<project name="Clover Report" default="current">

    <clover-format id="clover.format" type="${type}" orderBy="${orderBy}" filter="${filter}"/>
    <clover-setup initString="${cloverdb}"/>

    <clover-columns id="clover.columns">
        <totalChildren/>
        <avgMethodComplexity/>
        <uncoveredElements format="raw"/>
        <totalPercentageCovered format="longbar"/>
    </clover-columns>


    <target name="historical">
        <clover-report>
            <current outfile="${output}"  summary="${summary}">
                <format refid="clover.format"/>
                <testsources dir="${tests}"/>
                <columns refid="clover.columns"/>
            </current>
            <historical outfile="${historyout}" historydir="${history}">
                <format refid="clover.format"/>
                <columns refid="clover.columns"/>
            </historical>
        </clover-report>
    </target>

    <target name="current">
        <clover-report>
            <current outfile="${output}" title="${title}" summary="${summary}">
                <format refid="clover.format"/>
                <testsources dir="${tests}"/>
                <columns refid="clover.columns"/>
            </current>
        </clover-report>
    </target>

</project>

-Dmaven.clover.reportDescriptor=/path/to/clover-report.xml

<reportDescriptor>/path/to/clover-report.xml</reportDescriptor>

-Dmaven.clover.resolveReportDescriptor=true

<resolveReportDescriptor>true</resolveReportDescriptor>

mvn deploy:deploy-file -DgroupId=my.group.id -DartifactId=my-artifact-id -Dversion=X.X -Dclassifier=clover-report \
 -Dpackaging=xml -Dfile=/path/to/file -Durl=[url] -DrepositoryId=[id]

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.

You can also create a single database for all modules with singleCloverDatabase parameter set to true in clover2:setup goal.

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.

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:

<project>
  ...
  <reporting>
    <plugins>
      ...
      <plugin>
        <groupId>com.atlassian.maven.plugins</groupId>
        <artifactId>maven-clover2-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-clover2-plugin</artifactId>
        <configuration>
          ...
        </configuration>
        <executions>
          <execution>
            <phase>generate-sources</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>
...

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:

...
<pluginGroups>
    <pluginGroup>com.atlassian.maven.plugins</pluginGroup>
</pluginGroups>
...

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:

mvn clover2:setup test clover2:aggregate clover2:clover

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.