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 setup is required.

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

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

Telling Clover how to find its 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 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.

    Note

    For methods 2 and 3 above, as part of the test deployment process, you will need to copy the Clover registry file from the location on the build machine to the approriate directory on each of the execution machines. This needs to occur after the Clover build is complete, and 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.

Classpath Issues

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 particular environment being deployed to.