<clover-setup>
Description
The <clover-setup> task initialises Clover for use with your project. In Clover 1.0, Clover's operation was managed by setting various Ant properties. The <clover-setup> task simplifies this procedure.
Parameters
| Attribute | Description | Required |
| initstring | The Clover initString describes the location of the clover coverage database. Typically this is a relative or absolute file reference. Note that this value is not resolved relative to the project's base directory. | Yes |
| 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 |
| 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 |
| preserve | A boolean attribute which controls whether the instrumented source will be retained after compilation. | No; defaults to false |
| 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 |
| tmpdir | The directory into which Clover will write an instrumented copy of the source code. | No |
| flushpolicy | This attribute controls how Clover flushes coverage
data during a test run. Valid values are directed,
interval, or threaded.
For more information, see Flush Policies. |
No; defaults to directed |
| flushinterval | When the flushpolicy is set to interval or threaded this value is the minimum period between flush operations (in milliseconds) | No |
| relative | This controls whether the initstring parameter is treated as a relative path or not. | No; defaults to false |
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 convenience method to set these properties. This means that builds that use the Clover 1.0 property set will continue to operate as expected.
Nested Elements of <clover-setup>
<files>
An Ant patternset element which controls which files are included or excluded from Clover instrumentation.
<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.
<methodContext>
Specifies a method Context definition. See Using 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 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 |
<statementContext>
Specifies a statement Context definition. See Using 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 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 |
Examples
<clover-setup initstring="clover-db/coverage.db"/>
This example is the minimal setup to use clover. In this case the clover coverage database is located in the clover-db relative directory.
<clover-setup initstring="clover-db/coverage.db"
enabled="${enable}"
<files>
<exclude name="**/optional/**/*.java"/>
</files>
</clover-setup>
This example shows the use of a property, "enable", to control whether Clover instrumentation is enabled. Also the instrumentation will exclude all java source files in trees named "optional". Note that the fileset can also be referenced using a refid attribute.
<clover-setup initstring="clover-db/coverage.db"
enabled="${coverage.enable}"
<fileset dir="src/main">
<contains text="Joe Bloggs"/>
</fileset>
</clover-setup>
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:
<clover-setup initstring="clover-db/coverage.db"
flushpolicy="interval"
flushinterval="5000"/>
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.
<clover-setup initstring="clover-db/coverage.db"
clovercompiler="jikes"/>
This example will pass compilation to the "jikes" compiler once instrumentation is complete.