Working with Distributed Applications

In some cases the application you wish to test has many components running on separate nodes in a network, or even on disconnected machines. You can use Clover to test such applications, although some additional configuration is required.

When deploying your application in container environments, you should also check to ensure that Clover has sufficient permissions to function.

When deploying, please ensure you deploy your clovered version of the war/ear file. The clovered version of the war/ear will have a "-clover" in the name and can usually be found in the target/clover directory.

For example, the filename could resemble this: money-test-tutorial-1.0-SNAPSHOT-clover.jar

On this page:

Collecting Overall Coverage from Distributed Builds

The first step in setting up coverage from distributed builds is to configure Clover for overall coverage reporting.

Step 1: Understanding the Clover 'initstring'

At build time, Clover constructs a registry of your source code, and writes it to a file at the location specified in the Clover initialisation string (initstring). When Clover-instrumented code is executed (e.g. by running a suite of unit tests), Clover looks in the same location for this registry file to initialise itself. Clover then records coverage data and writes coverage recording files next to the registry file during execution. See Clover Database Structure for more information.

Step 2: Choosing a Location for the Clover Registry

If you are deploying and running your Clover-instrumented code on different machines, you must provide a way for Clover to find the registry file, and provide a place for Clover to write coverage recording files; otherwise no coverage will be recorded.

Clover provides three different ways to achieve this:

1. Specify an initstring that is a globally accessible file path
   The compile-time initstring should be an absolute path to the same filesystem location, and be accessible and writable from the build machine and all execution machines. This could be a path on shared drive or filesystem.
   OR:
2. Specify an initstring that is a relative path, resolved at runtime
   The compile-time initstring represents a relative path (relative to the CWD of each execution context). To do this you need to specify relative="yes" on the <clover-setup> task.
   OR:
3. Specify an initstring at runtime via system properties
   You can override the Clover initstring at runtime via system properties. Two (three?) system properties are supported:

   clover.initstring	If not null, the value of this property is treated as an absolute file path to the Clover registry file
   clover.initstring.basedir	If not null (and the clover.initstring systyem property is not set), the value of this property is used as the base directory for the file specified at compile-time in the initstring to resolve the full path to the Clover registry.
   clover.initstring.prefix	If not null (and the clover.initstring or clover.initstring.basedir system properties are not set), the value of this property is prepended to the string value of compile-time specified initstring to resolve the full path to the Clover registry.

   To set one of these properties, you need to pass it on the command line when Java is launched, using the -D parameter:

   java -Dclover.initstring=... myapplication.Server
   

   For application servers, this may involve adding the property to a startup script or batch file.
   

   For methods two and three in the sequence above, you will need to copy the Clover registry file from the location on the build machine to the appropriate directory on each of the execution machines (as part of the test deployment process).
   This needs to occur:
   a. after the Clover build is complete, and
   b. before you run your tests.

   Once test execution is complete, you will need to copy the coverage recording files from each remote machine to the initstring path on the build machine in order to generate coverage reports.

Step 3: Set Your Classpath Correctly

You must put clover.jar (or the appropriate Clover plugin jar) in the classpath for any JVM that will load classes that have been instrumented by Clover. How you go about this depends on the nature of the application you are testing and the environment you are deploying to.

In some cases, the clover.jar must be on the classpath of the actual webserver, not just on the classpath of the webapp that is instrumented. This is to ensure Clover can properly flush its coverage data when the JVM of the webserver is shutdown.

Collecting Per-Test Coverage from Distributed Builds

The steps below require you to have carried out the previous steps on this page (related to 'Collecting Overall Coverage from Distributed Builds').

Enabling or Disabling Distributed Coverage at Runtime

Clover's Distributed Coverage feature is enabled at runtime by making use of command-line options.

This can be done without the need for re-instrumentation or compilation of source files.

Enabling Distributed Coverage
Distributed coverage can be enabled via setting this System property:

 -Dclover.distributed.coverage=ON 

This will enable distributed coverage with default settings.
Clover also needs to know which JVM is hosting your unit tests, by providing the following system property:

 -Dclover.server=true 

Disabling Distributed Coverage
Distributed coverage can be disabled by setting this System property on either the Test or the Application JVM:

-Dclover.distributed.coverage=OFF 

This will turn off distributed coverage for the JVM in which this is set, regardless of what was instrumented.

For more configuration options and how to do this in Ant and Maven, see the Clover-for-Ant and Clover-for-Maven 2 documentation.

Configuration Complete
Distributed Per-Test Coverage in Clover will now operate when running distributed builds. Detailed reports will now be available.