clover-instr

Description

The <clover-instr> task produces instrumented versions of sets of source files. These can then be compiled in place of the original source to produce an instrumented build.

The <clover-instr> task is provided for users who can't make use of the standard <clover-setup> integration task. The <clover-setup> task offers a simpler and less intrusive integration option for most users.

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

<clover-instr>
    <distributedCoverage/>
    <fileset/>
    <methodcontext/>
    <statementcontext/>
    <testsources>
        <testclass>
            <testmethod/>
        </testclass>
    </testsources>
</clover-instr>

Parameters

Attribute	Description	Required
destdir	The directory into which Clover will write an instrumented copy of the source code.	Yes.
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`, relative to the project's base directory.	No.
flushinterval	When the flushpolicy is set to interval or threaded this value is the minimum period between flush operations (in milliseconds).	No.
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 for `directed`, 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`.
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`'.
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`.
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`'.
relative	This controls whether the `initstring` parameter is treated as a relative path or not.	No; defaults to '`false`'.
srcdir	The directory of source code to instrument.	Yes, unless a nested clover-instr element is used.
source	The source level to process source files at. It is recommended that you set this parameter, either here or on `<javac>` invocations.	No; defaults to the Java version detected at runtime.

Nested Elements of <clover-instr>

<distributedCoverage>

This element 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`'

All attributes are optional.

<fileset>

Specifies a set of source files to instrument.

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

<statementContext>

Specifies a statement 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 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.

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

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

<testsources dir="tests">
<and>
  <testclass annotation="Specification"/>
  <testclass annotation="Test"/>
</and>
<testsources>

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

<testsources dir="tests">
<or>
  <testclass name=".*Spec"/>
  <testclass name=".*Test"/>
</or>
<testsources>

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.

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

<testsources dir="tests">
  <testclass>
    <testmethod annotation="Specification"/>
    <testmethod name="^should.*"/>
    <testmethod name="^must.*"/>
  </testclass>
<testsources>

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

<clover-instr srcdir="src" destdir="instr"/>

Produce an instrumented copy of all source files in the srcdir into the destdir. The Clover registry is at the default location.

<clover-instr destdir="instr"/>
     <fileset dir="src">
       <include name="**/*.java"/>
     </fileset>
  </clover-instr>

This example achieves the same as the first example, but using an embedded fileset.

<clover-instr destdir="instr"/>
     <testSources dir="src">
         <include name="**/*Test.java"/>
         <testclass name=".*Test">
             <testmethod name=".*Bag.*"/> <!-- only the Bag related tests -->
         </testclass>
     </testSources>
  </clover-instr>

This example produces an instrumented copy which recognises 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".

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-instr flushpolicy="interval" flushinterval="5000" srcdir="src" destdir="instr" />

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

Specifying the location of the Clover Database.

By default, Clover writes its internal database to the .clover directory relative to the project's basedir. To override this location, use the initstring attribute.

<clover-instr initstring="clover-db/coverage.db" srcdir="src" destdir="instr"/>

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.

All Versions

Clover 2.6 Documentation

Child pages

Description

Parameters

Nested Elements of <clover-instr>

<distributedCoverage>

Parameters

<fileset>

<methodContext>

Parameters

<statementContext>

Parameters

<testsources>

Nested elements of <testsources>

<testclass>

Parameters

<and>

<or>

Nested elements of <testclass>

<testmethod>

Parameters

Examples

Interval Flushing

Specifying the location of the Clover Database.