Instrument, Collect, and Aggregate Coverage

Originally published on 2010-07-07; fully revised and updated.

This guide explains how to use Maven Clover in a distributed test setup, where instrumented code runs on multiple servers instead of only on the build machine. It is useful for Java teams running integration or system tests remotely and needing a single, consolidated code coverage report.

This revision preserves the original workflow and legacy clover2 Maven goals from the source post: configure Clover, build with instrumentation, deploy to test nodes, run tests, and generate coverage reports.

Why distributed coverage needs extra steps

In a local-only build, instrumentation, execution, and report generation all happen on one machine. In distributed testing, Clover data is split across remote servers, so you must move the right files at the right time.

• Build machine creates Clover-instrumented artifacts and a Clover registry database file.
• Test servers execute instrumented code and write runtime coverage recording files.
• Coverage recording files must be copied back before generating the final report.

End-to-end Clover workflow for distributed applications

flowchart TD
    A[Configure Clover in Maven] --> B[Build instrumented artifacts]
    B --> C[Deploy artifacts to test servers]
    C --> D[Copy Clover registry DB to each test node]
    D --> E[Run remote tests]
    E --> F[Collect coverage recording files]
    F --> G[Copy recordings to build machine]
    G --> H[Generate aggregate Clover report]

1) Configure Clover in Maven

Add the Clover plugin to your pom.xml. For multi-module projects, define it in the parent POM so all modules inherit a consistent setup.

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>com.atlassian.maven.plugins</groupId>
        <artifactId>maven-clover2-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>Code language: HTML, XML (xml)

The original workflow uses command-line goals for setup, aggregation, and report generation, so many teams keep plugin configuration minimal and drive execution from CI jobs.

2) Build all components with Clover enabled

Run the build with Clover instrumentation enabled:

mvn -U clover2:setup package clover2:aggregateCode language: CSS (css)

Expected logs should show Clover loading, creating a database, and instrumenting source files.

[INFO] Loaded from: .../clover-2.6.3.jar
[INFO] Clover: Commercial License registered to ...
[INFO] Creating new database at '.../target/clover/clover.db'.
[INFO] Processing files at 1.5 source level.
[INFO] Clover all over. Instrumented ... files (... package).Code language: JavaScript (javascript)

3) Deploy instrumented build and Clover registry to test servers

Deploy the instrumented build as you normally deploy test artifacts. In addition, copy the Clover registry database (created during build, often referenced by Clover initstring) to each test server where instrumented code will run.

• Deploy instrumented binaries to all test nodes.
• Copy the Clover registry DB to the path expected at runtime.
• Ensure the runtime user can read and write in that folder.

The source article also documents Java policy permissions used in older secured JVM setups:

grant codeBase "file:/path/to/clover.jar" {
  permission java.util.PropertyPermission "*", "read";
  permission java.io.FilePermission "<>", "read, write";
  permission java.lang.RuntimePermission "shutdownHooks";
};Code language: JavaScript (javascript)

Legacy server paths mentioned in the original process:

%JAVA_HOME%/jre/lib/security
%JAVA_HOME%/jre/lib/extCode language: JavaScript (javascript)

4) Run tests remotely and collect coverage recordings

Run automated or manual tests as usual. While instrumented code executes, Clover writes coverage recording files near the registry DB. The original naming pattern is described as:

xxx.dbHHHHHHH_TTTTTTTTTT
clover.dbHHHHHHH_TTTTTTTTTT.1Code language: CSS (css)

After test execution, copy all recording files from each remote node back to the build machine (to the expected initstring location) before report generation.

scp test-node-1:/opt/app/cloverCode language: PHP (php)

5) Generate and review the Clover report

Once coverage recording files are centralized on the build machine, generate the report:

mvn clover2:cloverCode language: CSS (css)

Review the generated coverage output and verify that all remote test runs contributed data. Missing node files typically lead to lower-than-expected coverage.

Maven goals used in this workflow

Goal or phase	Purpose in pipeline	When to run
clover2:setup	Prepare Clover instrumentation and registry data	Before compile/package
package	Build instrumented artifacts	Build stage
clover2:aggregate	Aggregate Clover results across modules	After module builds
clover2:clover	Generate final coverage report	After collecting remote recordings

Best practices and common pitfalls

• Keep Clover configuration centralized in the parent POM for multi-module builds.
• Use the same expected registry location between build and runtime environments.
• Validate write permissions on the folder that stores Clover DB and recording files.
• Collect recordings from every test node before generating reports.
• Treat the policy and jre/lib/ext guidance as legacy and verify against your current JDK/security model.