Using Distributed Per-test Coverage

This page contains instructions on how to collect per-test coverage from a set of functional tests, which run in multiple JVMs (Java Virtual Machines). This may be necessary when starting a web server with the Maven Cargo plugin or the Tomcat plugin, for example.

Why measure per-test coverage?

Clover's per-test coverage data gives you unique insight into how each of your tests exercises the codebase. Clover's per-test reporting gives statement level detail about the behaviour of each test. Furthermore, once you've measured per-test coverage, you can use Clover's powerful new test optimization feature, where Clover can choose a smart subset of tests to run for a given code change, saving you the time and hassle of running a full test suite for every change.

On this page:

To set up collection of per-test coverage from distributed builds, carry out the following steps.

Option 1. Enabling Distributed Coverage at Runtime

It is recommended, but not necessary, to enable distributed coverage collection at runtime. This can be done by defining the clover.distributed.coverage system property in all JVMs running Clovered code, including your Surefire JVM, and the JVM running your web server.

For the following examples, we are using the Maven Cargo plugin to start the webserver and the Maven Surefire plugin to run the tests.

Setting a System Property in the Maven Cargo plugin

The "clover.distributed.coverage" System Property must be set to "ON" in the Maven Cargo Plugin configuration.

<systemProperties>
    <clover.distributed.coverage>ON</clover.distributed.coverage>
</systemProperties>

TIP: the clover.distributed.coverage=ON takes default settings (host=localhost, port=1198, timeout=5000ms, numClients=0, retryPeriod=1000ms, name=clover.tcp.server). In case when you cannot use default settings, you can pass specific value for any of attributes using the "key=value" syntax passed as clover.distributed.coverage value:

host - host name of the "Clover Server"
port - port on which the Clover will listen
numClients - number of "Clover Clients" to connect until server starts test execution
timeout - connection timeout in miliseconds
retryPeriod - inverval between connection retries in miliseconds
name - name of the configuration (URL is host:port/name)

Example:

<systemProperties>
    <clover.distributed.coverage>host=myhost;port=7777;numclients=2</clover.distributed.coverage>
</systemProperties>

Setting a System Property in the Maven Surefire plugin

The following System properties must be set in the Maven Surefire Plugin configuration:

"clover.distributed.coverage" System Property must be set to "ON",
"clover.server" System Property must be set to "true".

<configuration>
   <forkMode>once</forkMode>
   <systemProperties>
       <property>
           <name>clover.server</name>
           <value>true</value>
       </property>
       <property>
           <name>clover.distributed.coverage</name>
           <value>ON</value>
       </property>
   </systemProperties>
</configuration>

Option 2. Activate Distributed Coverage during Instrumentation.

Step 1: Activate the Distributed Coverage Feature

To add the <distributedCoverage/> element to the maven-clover2-plugin configuration section, apply the following code:

<configuration>
   <distributedCoverage/>
</configuration>

This will enable distributed per-test coverage to be collected. Clover running in the JVM that hosts the tests will start a TCP server to do so. By default, it listens on localhost:1198 .

The <distributedCoverage> element takes the following nested elements:

Element name	Description	Required
host	The hostname the test JVM should bind to.	No; defaults to '`localhost`'
name	The name of this configuration.	No; defaults to '`tcp-config`'
numClients	The number of clients that need to connect to the test server before the tests will continue.	No; defaults to '`0`'
port	The port the test JVM should listen on.	No; defaults to '`1198`'
retryPeriod	The amount of time (in milliseconds) to wait before attempting to reconnect in the event of a network failure.	No; defaults to '`1000`'
timeout	The amount of time (in milliseconds) to wait before a connection attempt will fail.	No; defaults to '`5000`'

All attributes are optional.

Step 2: Specify the JVM running the Tests as the Server

Add the clover.server system property to the maven-surefire-plugin configuration section, and ensure the forkMode parameter is set to 'once':

<plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <forkMode>once</forkMode>
        <systemProperties>
            <property>
                <name>clover.server</name>
                <value>true</value>
            </property>
        </systemProperties>
    </configuration>
</plugin>

Execution

In order to run your tests and generate reports, you might need to copy Clover database (clover.db) and coverage recordings (clover.dbHHHHHHH_TTTTTTTTTT) between machines. You might also need to provide clover.jar at runtime. It depends on how your environment is configured and especially whether Clover database is accessible via shared network drive. Read the Using Clover in various environment configurations.

Child pages