Site announcement

We are switching off article comments on this website. Read about the upcoming changes to Atlassian Documentation.

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

Skip to end of metadata
Go to start of metadata

This tool copies and instruments a set of Java source files specified on the command line. The output of the instrumentation process is instrumented java source; you will then need to compile the instrumented source using a standard Java compiler.

Usage

Note: in Clover 3.1.x and older a class was named com.cenqua.clover.CloverInstr.

Params

-i, --initstring <file>

Clover initstring. This is the full path to the dbfile that will be used to construct/update to store coverage data.

-s, --srcdir <dir>

Directory containing source files to be instrumented. If omitted individual source files should be specified on the command line.

-d, --destdir <dir>

Directory where Clover should place the instrumented sources. Note that files will be overwritten in the destination directory.

Options

-dc, --distributedCoverage <string>Configuration for recording distributed pre-test coverage.

Valid keys and default values are: ON | OFF |

--dontFullyQualifyJavaLangIf set, then java.lang will not be used in instrumented source.

-e, --encoding <encoding>

Specify the file encoding for source files. If not specified, the platform default encoding is used.

-f, --flushinterval <int>

Tell Clover how often to flush coverage data when using either "interval" or "threaded" flushpolicy. Value in milliseconds.

--instrumentation <policy>

Set the instrumentation strategy. Valid values are "field" and "class". Default is "class".

--instrlevel <string>Set the instrumentation level. Valid values are "statement" and "method". Default is "statement".
--instrlambda <string>

Whether to instrument lambda functions. Valid values are:

  • "none"  - lambda functions will not be visible as "methods", code statements from a lambda body will become a part of an enclosing method
  • "expression" - only lambda functions in an expression-like form (e.g. "(a, b) -> a + b") are instrumented
  • "block" - only lambda functions written as code blocks (e.g. "() -> { return 123; }") are instrumented 
  • "all" - instrument all lambda functions

Since Clover 3.2.2. Default is "all" in 3.2.2-4.0.2 and "none" since 4.0.3.

See also Java 8 code instrumented by Clover fails to compile bug.

-p, --flushpolicy <policy>

Tell Clover which flushpolicy to use when flushing coverage data to disk. Valid values are "directed", "interval" and "threaded". With "interval" or "threaded", you must also specify a flushinterval using -f. The default value is "directed".

-mc --methodContext <name>=<regexp>Defines a single custom method context. May be supplied more than once. (The \ may be needed to prevent shell expansion)
-sc --statementContext <name>=<regexp>Defines a single custom statement context. May be supplied more than once. (The \ may be needed to prevent shell expansion)
-r, --relativeIf specified, the initstring is treated as a relative path, rather than being converted to an absolute path. This is useful for distributed testing environments.

--recordTestResults <true|false>        

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

--source <level>Set the language level for Clover to use when parsing files.

--sourceRoot <string>

Source root path prefix that will be ignored when evaluating the test inclusion patterns. This parameter is optional; it specifies what is trimmed from the beginning of the file path before the tests Include/Exclude Pattern is evaluated (see parameters below). For example, if you specify --sourceRoot /home/user/project/src, then pattern 'test/*.' would match a file in this location: '/home/user/project/src/test/Test.java'.
If you leave the --sourceRoot option out, the pattern would need to start with * or specify the full path '/home/user/project/src/test/.'

-v, --verbose

Enable verbose logging.

API Usage

CloverInstr provides a simple API that accepts an array of strings representing the command line arguments and returns an integer result code. The following fragment illustrates use of the API:

Examples

Find all java source files in the directory "src", copy and instrument them into the directory "build/instr", which will be constructed if it does not exist. Coverage database "clover.db" is initialised.

 

Copy and instrument the source files "Money.java" and "IMoney.java" into the directory "../../build/instr". Use the JDK1.4 grammar (i.e. support the 'assert' keyword).