This documentation is for Clover 4.0.x. Earlier versions are available here.

Skip to end of metadata
Go to start of metadata

On this page:

 

Description

The <clover-setup> task initialises Clover for use with your project.

The basic nesting of elements within the <clover-setup> task is as follows:

<clover-setup>
    <distributedCoverage/>
    <files/>
    <fileset/>
    <methodcontext/>
    <statementcontext/>
    <profiles/>
    <testsources> advanced users only
        <testclass>
            <testmethod/>
        </testclass>
    </testsources>
</clover-setup>

Parameters

All attributes of the <clover-setup> element support Java. However, as indicated in the last column of the following table, some of these attributes do not support Groovy.

Attribute

Description

Required

Groovy Support

clovercompiler

After instrumentation, Clover hands off compilation to the standard Ant compiler adapter (or the compiler specified by the build.compiler Ant property). This attribute specifies the adapter to use. It takes the same values as the standard Ant build.compiler property. If you wish to specify an alternative compiler, you can either set the build.compiler property or use this attribute.

No.

(error)

enabled

This controls whether Clover will instrument code during code compilation. This attribute provides a convenient control point to enable or disable Clover from the command line.

No; defaults to 'true'.

(tick)

flushinterval

When the flushpolicy is set to interval or threaded this value is the minimum period between flush operations (in milliseconds)

No.

(tick)

flushpolicy

This attribute controls how Clover flushes coverage data during a test run. Valid values are directed, interval, or threaded.

directed — Coverage data is flushed at JVM shutdown, and after an inline flush directive.

interval — Coverage data is flushed as fordirected, as well as periodically at a maximum rate based on the value of flushinterval. This is a 'passive' mode in that flushing potentially occurs as long as instrumented code is being executed.

threaded — Coverage data is flushed as for directed, as well as periodically at a rate based on the value of flushinterval. This is an 'active' mode in that flushing occurs on a separate thread and is not dependent on the execution of instrumented code.

For more information, see Using a Flush Policy.

No; defaults to 'directed'.

(tick)

fullyQualifyJavaLang

This should only be set to 'false' if you have defined a variable called 'java' in your source files. If false, Clover will instrument source files without using fully qualified java.lang names.

No; defaults to 'true'.

(error)

initstring

The Clover initString describes the location of the Clover coverage database. Typically this is a relative or absolute file reference, e.g. ${basedir}/build/clover.db. If not specified it defaults to .clover/clover.db, relative to the project's base directory.

No.

(tick)

instrumentationLevel

This setting can reduce accuracy to method level, to enhance the speed of instrumentation, compilation & test execution. Valid values are 'method' and 'statement'.

No; defaults to statement.

(tick)

instrumentLambda

Since 3.2.2. Whether Java 8 lambda functions shall be instrumented. If instrumented, they're treated like normal methods (and can be shown in HTML report and considered in code metrics, for example). Possible values:

  • none - do not instrument lambda functions,
  • expression - instrument lambdas in expression-like form, e.g. "(a, b) -> a + b",
  • block - instrument lambdas in code blocks, e.g. "(a, b) -> { return a + b; }"
  • all_but_reference - instrument lambdas written in any form except method references, e.g. "Math::abs()"

    (warning) available since Clover 4.0.5

  • all - instrument all lambda functions.

(warning) Due to Clover's restrictions related with code instrumentation and javac compiler's type inference capabilities, you may get compilation errors when expression-like lambda functions are passed to generic methods or types. In such case disable instrumentation of expression-like form (i.e. use the none or block setting). See the Java 8 code instrumented by Clover fails to compile Knowledge Base article for more details.

No; defaults to "all" in 3.2.2-4.0.2 and to "none" since 4.0.3.(error)

preserve

A boolean attribute which controls whether the instrumented source will be retained after compilation.

No; defaults to 'false'.

(error)

recordTestResults

If set to 'false', test results will not be recorded; instead, results can be added via the <testResults> fileset at report time. For more details please see 'Advanced Usage'.

No; defaults to 'true'. 

(tick)

relative

This controls whether the initstring parameter is treated as a relative path or not.

No; defaults to 'false'.

(tick)

source

The default source level to process source files at. Note that setting the source attribute on the <javac> target will override this setting.

No.

(error)

tmpdir

The directory into which Clover will write an instrumented copy of the source code.

No.

(tick)

It is important to note that the Clover compiler adapter still picks up its settings from the set of Clover Ant properties. The <clover-setup> task provides a convenient method to set these properties. This means that builds that use the Clover 1.0 property set will continue to operate as expected.
(warning) Do not set the 'compiler' attribute on the <javac/> task as this overrides the Clover compiler set up by <clover-setup>. Use the 'clovercompiler' attribute instead.

Nested Elements

<distributedCoverage>

This element, which supports both Java and Groovy, turns on Clover's distributed coverage feature, enabling the collection of per-test coverage data, when your test environment requires more than one JVM (Java Virtual Machine).

Parameters

Attribute name

Description

Required

name

The name of this configuration.

No; defaults to 'tcp-config'

port

The port the test JVM should listen on.

No; defaults to '1198'

host

The hostname the test JVM should bind to.

No; defaults to 'localhost'

timeout

(a number) The amount of time (in milliseconds) to wait before a connection attempt will fail.

No; defaults to '5000'

numClients

(a number) The number of clients that need to connect to the test server before the tests will continue.

No; defaults to '0'

retryPeriod

(a number) The amount of time (in milliseconds) to wait before attempting to reconnect in the event of a network failure.

No; defaults to '1000'

(info) All attributes are optional.

<files>

An Ant patternset, relative to the top level package (e.g. com/atlassian/clovertest), element which controls which files are included or excluded from Clover instrumentation. Use this when you wish to exclude files based on packages.

Note

The <useclass> sub-element has been deprecated and has no effect.

<fileset>

As of Clover 1.2, <clover-setup> also supports multiple Ant <filesets>. These give greater flexibility in specifying which source files are to be instrumented by Clover. This is useful when you have more than one source base and only want some of those source bases to be instrumented. This can be difficult to setup with patterns. Filesets also allow much greater flexibility in specifying which files to instrument by facilitating the use of Ant's fileset selectors. Use this when you wish to exclude files based on directory structure.

The <fileset> tag has a "dir" attribute and uses standard Ant directory scanner to find sources for exclusion. It means that at the time when <clover-setup> is called the directory must be present and files to be excluded/included too.

<methodContext>

Specifies a method Context definition. See Using Coverage Contexts for more information.

Parameters

Attribute

Description

Required

name

The name for this context. Must be unique, and not be one of the reserved context names (see Using Coverage Contexts).

Yes.

regexp

A Perl 5 Regexp that defines the context. This regexp should match the method signatures of methods you wish to include in this context. Note that when method signatures are tested against this regexp, whitespace is normalised and comments are ignored.

Yes.

maxComplexityMatch a method to this pattern if its cyclomatic complexity is not greater than maxComplexity. In other words - all methods with complexity <= maxComplexity will be filtered out.No.
maxStatementsMatch a method to this pattern if its number of statements is not greater than maxStatements. In other words - all methods with statements <= maxStaments will be filtered out.No.
maxAggregatedComplexitySince 3.1.10. Match a method to this pattern if its aggregated cyclomatic complexity is not greater than maxAggregatedComplexity. In other words - all methods with aggregated complexity <= maxAggregatedComplexity will be filtered out. Aggregated complexity metric is a sum of the method complexity and complexity of all anonymous inline classes declared in the method.No.
maxAggregatedStatementsSince 3.1.10. Match a method to this pattern if its number of aggregated statements is not greater than maxAggregatedStatements. In other words - all methods with aggregated statements <= maxAggregatedStaments will be filtered out. Aggregated statements metric is a sum of the method statements and statements of all anonymous inline classes declared in the method.No.

 

What is the difference between maxComplexity and maxAggregatedComplexity or maxStatements and maxAggregatedStatements?

Aggregated metrics calculate method statements/complexity including the code of all anonymous inline classes declared inside the method. Thanks to this, it is possible to distinguish between a trivial single-statement method like:

and a single-statement method which actually returns more complex data, like:

 

If you would use a method context filter with maxStatements attribute, like the following:

then both getNumber() and getListener() methods would be filtered-out, because each of them contains only one statement: "return <xxx>".

 

If you would use new maxAggregatedStatements, for instance:

then the getNumber() would be filtered-out and the getListener() method would not be filtered out (because it contains 4 statements in total - 1 "return" statement from the method itself and 3 "System.out.println()" statements from anonymous class).

 

Regular expression tip:

(lightbulb) If you would like to filter-out all methods, except those having a specific name, you could write a negative-look-ahead regular expression. For example:

will filter-out all methods having not more than one statement, except those which are named getRunnable or getListener.

 

 

<statementContext>

Specifies a statement Context definition. See Using Coverage Contexts for more information.

This element does not support Groovy.

Parameters

Attribute

Description

Required

name

The name for this context. Must be unique, and not be one of the reserved context names (see Using Coverage Contexts).

Yes.

regexp

A Perl 5 Regexp that defines the context. This regexp should match statements you wish to include in this context. Note that when statements are tested against this regexp, whitespace is normalised and comments are ignored.

Yes.

 

<profiles>

Since 3.1.11. Optional element. Defines a list of Clover profiles, which can be selected at runtime by providing a clover.profile=<name> system property. Thanks to this you can change some of Clover's behaviour without code recompilation.

 

<profile>

Since 3.1.11. Contains a definition of a single runtime profile.

Parameters

Attribute

Description

Required

name

The name for this profile; name must be unique among profiles. There must be one profile named "default".

No. Defaults to "default".

coverageRecorder

Type of coverage recorder which will be used for gathering coverage data at runtime. Possible values: FIXED, GROWABLE, SHARED (case insensitive).

(warning) Warning: we strongly recommend using the default setting. Do not change until you deeply understand how it works.

No. Defaults to "FIXED".

Nested elements

<distributedCoverage/>

(lightbulb)Note: a definition in <profile>/<distributedCoverage> element has priority over the <clover-setup|clover-instr>/<distributedCoverage> element.

Selecting clover.profile at runtime

Clover profile is being selected at runtime using the following algorithm:

  • Are there any profiles defined in compiled code?
    • yes -
      • 1. read the clover.profile system property. is it defined?
        • yes - use the value as profile name
        • no - use the "default" profile name
      • 2. is the profile name found on list of defined profiles?
        • yes - use settings from this profile
        • no - use system settings (default coverage recorder etc...)
    • no - use system settings (default coverage recorder etc...)

So it fall-backs to default system settings in case of missing profile.

 

 

<testsources>

<testsources> is an Ant fileset which should only be used if Clover's default test detection is not adequate. Clover's default test detection algorithm is used to distinguish test cases if this element is omitted.

To have test sources reported in a separate tree to your application code, use the <testsources/> element in the <clover-report/> task.

Nested elements of <testsources>
<testclass>

<testclass> can be used to include only specific test classes.

Parameters

Attribute

Description

Required

name

A regex on which to match the test class's name.

No.

super

A regex on which to match the test class's superclass.

No.

annotation

A regex on which to match the test class's annotation.

No.

package

A regex on which to match the test class's package.

No.

tag

A regex on which to match the test class's javadoc tags.

No.

(info) For more information about regular expressions, please visit http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html#sum.

<and>

<and> can be used to specify multiple instances of <testclass>, all of which must be matched for a class to be detected as a test, e.g.:

In this example, a class will only be recognised as a test if it has "Specification" and "Test" annotations.

<or>

<or> can be used to specify multiple instances of <testclass>, any of which must be matched for a class to be detected as a test, e.g.:

In this example, a class will be recognised as a test if its name matches ".*Spec", or its name matches ".*Test".

Nested elements of <testclass>
<testmethod>

<testmethod> can be used to perform more fine grained detection of test methods.

(warning) Clover matches methods only; it does not match constructors (CLOV-1339).

Parameters

Attribute

Description

Required

name

A regex on which to match the test method's name.

No.

annotation

A regex on which to match the test method's annotation.

No.

tag

A regex on which to match the test method's javadoc tags.

No.

returntype

A regex on which to match the return type of the method, e.g.:

  • ".*" will match any return type.
  • "void" will match methods with no return type.

No.

Note that you can include multiple instances of <testmethod>, in which case they will be treated as 'or' clauses, e.g.:

In this example, a method will be recognised as a test if its annotation is "Specification", or its name matches "^should*", or its name matches "^must*".

Examples

This example is the minimal setup to use Clover. In this case, the Clover coverage database is located in the .clover relative directory.

This example shows the use of a property, "enable", to control whether Clover instrumentation is enabled. Additionally, the instrumentation will exclude all Java source files in trees belonging to the com.atlassian.clover.* packages (please note, that even if the files belong in the src/main or src/test directory, you cannot specify src, main or test as these are directories and do not belong to the package structure. When using files, you need to filter by files or the packages as in the example above). Note that the fileset can also be referenced using a refid attribute.

This example instruments all source files in the src/main directory tree that contain the string "Joe Bloggs". Ant's filesets supports a number of these selectors. Please refer to the Ant manual for information on these selectors.

Interval Flushing

By default Clover will write coverage data to disk when the hosting JVM exits, via a shutdown hook. This is not always practical, particularly when the application you are testing runs in an Application Server. In this situation, you can configure Clover to use "interval" flushing, where coverage data is written out periodically during execution:

The "flushinterval" defines in milliseconds the minimum interval between coverage data writes.

Specifying a delegate compiler

Clover provides the optional "clovercompiler" attribute to allow specification of the java compiler to delegate to once instrumentation is completed. The attribute accepts the same values "compiler" attribute of the Ant Javac Task.

This example will pass compilation to the "jikes" compiler once instrumentation is complete.

Specifying the location of the Clover Coverage database

By default, Clover writes its internal database to the .clover/clover.db file relative to the project's base directory. To override this location, use the initstring attribute, e.g.:

This example will use clover-db/coverage.db as the location for the Clover database. Note that the directory clover-db should exist before running this task.

Specifying a custom test matcher

By default, Clover attempts to detect your test classes and methods. Clover's default behaviour may be overridden via the following:

This example tells Clover to recognise all of the following as tests: classes in the directory "src"; classes in files whose names end with "Test"; methods whose names contain with "Bag".

 

Troubleshooting

Clover does not support parallel compilation

You cannot use <parallel/> task for code compilation, for instance:

will produce error message like:

[clover] Error finalising instrumentation:
   [clover] java.io.IOException: Failed to move tmp registry file /myproject/.clover/clover3_1_6.db.tmp to final registry file