Home | Forums

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

When deploying you 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 it's 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 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.
  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.
  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 System 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.basedirSystem 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 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'll need to copy the coverage recording files from each remote machine to the initstring path on build machine 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.

Restricted Security Environments

In some java environments, such as J2EE containers, applet environments, or applications deployed via Java Webstart, security restrictions are applied to hosted java code that restrict access to various system resources.

To use Clover in these environments, Clover needs to be granted various security permissions for it to function. This requires the addition of a Grant Entry to the security policy file for the Clover jar. For background on the syntax of the policy file, see Default Policy Implementation and Policy File Syntax. For background on setting Java security policies in general, see Permissions in the Java 2 SDK.

Recommended Permissions

Clover requires access to the java system properties for runtime configurations, as well as read write access to areas of the file system to read the clover coverage database and to write coverage information. Clover also uses a shutdown hook to ensure that it flushes any as yet unflushed coverage information to disk when java exits. To support these requirements, the following security permissions are recommended:

grant codeBase "file:/path/to/clover.jar" {
    permission java.util.PropertyPermission "*", "read";
    permission java.io.FilePermission "<<ALL FILES>>", "read, write";
    permission java.lang.RuntimePermission "shutdownHooks";