clover2:instrument-test

Full name:

com.atlassian.maven.plugins:maven-clover2-plugin:4.0.5:instrument-test

Description:

This goal behaves exactly like the instrument goal, however when forking the lifecycle - it runs only to the 'test' phase instead of all the way to the 'install' phase.

This goal should be used as an optimization - ie. if the phases after 'test' take a very long time to run.

Instrument all sources using Clover and forks a custom lifecycle to execute project's tests on the instrumented code so that a Clover database is created.

Attributes:

  • Requires a Maven project to be executed.
  • Invokes the execution of the lifecycle phase test prior to executing itself.
  • Executes in its own lifecycle: clover.

Required Parameters

Name Type Since Description
cloverMergeDatabase String - The location of the merged clover database to create when running a report in a multimodule build.
Default value is: ${project.build.directory}/clover/cloverMerge.db.
User property is: maven.clover.cloverMergeDatabase.
cloverOutputDirectory String - The directory where the Clover plugin will put all the files it generates during the build process. For example the Clover plugin will put instrumented sources somewhere inside this directory.
Default value is: ${project.build.directory}/clover.
project MavenProject -

The Maven project instance for the executing project.

Note: This is passed by Maven and must not be configured by the user.


User property is: project.

Optional Parameters

Name Type Since Description
cloverDatabase String - The location of the Clover database.
User property is: maven.clover.cloverDatabase.
cloveredArtifactExpiryInMillis long -

The difference (in milliseconds) that a -clover classified artifact can have to a non-clover classified artifact.

If the -clover classified artifact is more than cloveredArtifactExpiryInMillis older than the non-clover classified artifact, then the non-classified artifact will be used.

This setting defaults to 2000.


Default value is: 2000.
User property is: maven.clover.cloveredArtifactExpiryInMillis.
copyExcludedFiles boolean - If set, then the maven-clover2-plugin will not copy files that were excluded, across to the target/clover directory. This is useful if the build is also using plugins such as the maven-gwt-plugin, that scans for resources, and skips a step if none are found. Otherwise, setting this to false could well cause build failures.
Default value is: true.
User property is: maven.clover.copyExcludedFiles.
debug boolean - If you wish to enable debug level logging in just the Clover plugin, set this to true. This is useful for integrating Clover into the build.
Default value is: false.
User property is: maven.clover.debug.
distributedCoverage DistributedCoverage -

The configuration for distributed coverage collection by Clover.

If present, default values will be used and coverage will be collected across JVMs.

Optional nested elements (and their defaults) of distributedCoverage are:

  • host - the host name of the JVM running the tests. default: localhost
  • port - the port that Clover can bind to in the host JVM. default: 1198
  • numClients - the number of clients expected to attach to the Test JVM. The test JVM will wait until numClients have connected before continuing. default: 0
  • timeout - the amount of time to wait for a response from a remote JVM before shunning it. default: 5000
  • retryPeriod - the amount of time a client should wait between reconnect attempts. default: 1000

encoding String - The character encoding to use when parsing source files.
User property is: maven.clover.encoding.
excludes Set - The list of file to exclude from the instrumentation. Patterns are resolved against source roots.
excludesList String - The comma seperated list of file to exclude from the instrumentation. Patterns are resolved against source roots.
User property is: maven.clover.excludesList.
flushInterval int - When the Clover Flush Policy is set to "interval" or threaded this value is the minimum period between flush operations (in milliseconds).
Default value is: 500.
User property is: maven.clover.flushInterval.
flushPolicy String - The Clover flush policy to use. Valid values are directed, interval and threaded.
Default value is: threaded.
User property is: maven.clover.flushPolicy.
groverJar File 3.1.8

By default, Maven Clover Plugin generates the ${java.io.tmpdir}/grover*.jar file during setup, which is next being added as the dependent artifact to the build. As the file has generated, unique name and the jar is not being removed at the end of the build, these files can litter the temporary directory.

By setting this parameter you can:

a) specify constant file name for generated artifact,

b) choose location different than ${java.io.tmpdir}.

However, you must ensure that:

a) grover.jar will not be deleted till end of the build (for example don't put into ./target directory and next run mvn clover2:setup clean)

b) grover.jar will not be shared among builds with different Maven Clover Plugin versions used (for example if ProjectA uses Clover v 3.1.8 and ProjectB uses Clover v 3.1.9 then they shall have different groverJar locations defined)


User property is: maven.clover.groverJar.
includes Set - The list of file to include in the instrumentation. Patterns are resolved against source roots. Defaults are '**/*.java, **/*.groovy' which are overwritten if <includes> is set by the user
includesAllSourceRoots boolean -

Till 3.1.11: whether the Clover plugin should instrument all source roots (for example src/main/java, src/main/groovy, target/generated-sources, so including the generated sources) or whether it should only instrument the main source root (usually src/main/java).

Since 3.1.12: whether the Clover plugin should instrument all source roots (for example src/main/java, src/main/groovy, target/generated-sources, so including the generated sources) or whether it should instrument non-generated source roots (i.e. all roots except target/generated-sources/*)


Default value is: false.
User property is: maven.clover.includesAllSourceRoots.
includesList String - The comma seperated list of files to include in the instrumentation. Patterns are resolved against source roots. Defaults are **.java which are overwritten if <includes> is set by the user
User property is: maven.clover.includesList.
includesTestSourceRoots boolean - Whether the Clover plugin should instrument test source roots.
Default value is: true.
User property is: maven.clover.includesTestSourceRoots.
instrumentLambda String 3.2.2

Define whether lambda functions shall be instrumented: Valid values are:

  • none - do not instrument lambda functions (note: statements inside lambdas will become a part of a parent function)
  • expression - instrument only expression-like lambdas, e.g. (a,b) -> a + b
  • block - instrument block lambdas, e.g. () -> { foo(); }
  • all_but_reference - instrument lambdas written in any form except method references, e.g. Math::abs
  • all - instrument all forms of lambda functions

Default is 'all' for 3.2.2-4.0.2 and 'none' since 4.0.3.

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


Default value is: none.
User property is: maven.clover.instrumentLambda.
instrumentation String -

The level to instrument to. Valid values are 'method' or 'statement'. Default is 'statement'.

Setting this to 'method' greatly reduces the overhead of enabling Clover, however limited or no reporting is available. The current use of setting this to method is for Test Optimization only.


User property is: maven.clover.instrumentation.
jdk String -

Which Java language level Clover shall use to parse sources. Valid values are:

  • 1.3
  • 1.4 (introduces 'assert' keyword)
  • 1.5 ('enum' keyword and generics)
  • 1.6 (no language changes)
  • 1.7 (String in switch, try with resources, binary literals, underscores in literals)
  • 1.8 (lambda expressions, default methods in interfaces)

By default Clover instruments using the highest language level supported.


User property is: maven.clover.jdk.
license String - The full Clover license String to use. If supplied, this certificate will be used over licenseLocation. NB. newline chars must be preserved. A trial Clover license can be generated here.
User property is: maven.clover.license.
licenseLocation String - A Clover license file to be used by the plugin. The plugin tries to resolve this parameter first as a resource, then as a URL, and then as a file location on the filesystem. A trial Clover license can be generated here.
User property is: maven.clover.licenseLocation.
methodContexts Map -

Specifies the custom method contexts to use for filtering specific methods from Clover reports.

e.g.
<main>public static void main\(String args\[\]\).*</main>

will define the context called 'main' which will match all public static void main methods.


repositoryPollutionProtection boolean 4.0.4

Try to protect your build from installing instrumented artifacts into local ~/.m2 cache or deploying them to a binaries repository. If this option is enabled, Clover will fail a build whenever it detects that 'install' or 'deploy' phase is about to be called. It will also fail a build if it detects that an artifact having multiple classifiers (e.g. "-clover-tests.jar"), which are not supported by Maven, is about to be installed under original name (e.g. "-tests.jar").

Please note that this flag may not protect from all possible cases.


Default value is: false.
User property is: maven.clover.repositoryPollutionProtection.
scope String - When creating the clover.jar dependency, what scope to use. This may be one of: compile, test, provided etc. If not specified - provided will be used.
User property is: maven.clover.scope.
setTestFailureIgnore boolean 3.1.9

If set to true, Clover will add several properties to the build configuration which disable a build failure for following plugins:

  • maven-surefire-plugin (maven.test.failure.ignore=true)
  • maven-failsafe-plugin (maven.test.failure.ignore=true)
  • maven-checkstyle-plugin (checkstyle.failOnViolation=false)
  • maven-pmd-plugin (pmd.failOnViolation=false)

Thanks to this, build continues despite test failures or code validation failures and thus it is possible to generate a Clover coverage report for failed tests at the end of the build.

Note: before version 3.1.9 the testFailureIgnore property was set to true for the forked Clover lifecycle ('instrument' goal) for 'test' and 'integration-test' phases. Since 3.1.9 it is no longer set.


Default value is: false.
User property is: maven.clover.setTestFailureIgnore.
singleCloverDatabase boolean - If true, then a single cloverDatabase will be used for the entire project. This flag will be ignored if a custom cloverDatabase location is specified.
Default value is: false.
User property is: maven.clover.singleCloverDatabase.
skip boolean - A flag to indicate not to run clover for this execution. If set to true, Clover will not be run.
Default value is: false.
User property is: maven.clover.skip.
skipGroverJar boolean 3.1.8

By default, Maven Clover Plugin generates the ${java.io.tmpdir}/grover*.jar file during setup, which is next being added as the dependent artifact to the build. As the file has generated, unique name and the jar is not being removed at the end of the build, these files can litter the temporary directory.

In case when there is no Groovy code in the project, this parameter can be set to true in order to disable generation of grover.jar artifact.


Default value is: false.
User property is: maven.clover.skipGroverJar.
snapshot File - The location to store the clover snapshot file. This file needs to persist between builds to enable Clover's build optimization feature. If not specified, the snapshot will be stored next to the cloverDatabase.
User property is: maven.clover.snapshot.
staleMillis int - Sets the granularity in milliseconds of the last modification date for testing whether a source needs reinstrumentation.
Default value is: 0.
User property is: maven.clover.staleMillis.
statementContexts Map - Specifies the custom statement contexts to use for filtering specific statements from Clover reports. e.g.
<log>^LOG\..*</log>
defines a statement context called "log" which matches all LOG statements.
useCloverClassifier boolean - Whether or not to include the -clover classifier on artifacts.
Default value is: true.
User property is: maven.clover.useCloverClassifier.
useFullyQualifiedJavaLang boolean - Use the fully qualified package name for java.lang.* classes.
Default value is: true.
User property is: maven.clover.useFullyQualifiedJavaLang.
waitForFlush boolean -

If true we'll wait 2*flushInterval to ensure coverage data is flushed to the Clover database before running any query on it.

Note: The only use case where you would want to turn this off is if you're running your tests in a separate JVM. In that case the coverage data will be flushed by default upon the JVM shutdown and there would be no need to wait for the data to be flushed. As we can't control whether users want to fork their tests or not, we're offering this parameter to them.


Default value is: true.
User property is: maven.clover.waitForFlush.

Parameter Details

cloverDatabase:

The location of the Clover database.
  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.cloverDatabase

cloverMergeDatabase:

The location of the merged clover database to create when running a report in a multimodule build.
  • Type: java.lang.String
  • Required: Yes
  • User Property: maven.clover.cloverMergeDatabase
  • Default: ${project.build.directory}/clover/cloverMerge.db

cloverOutputDirectory:

The directory where the Clover plugin will put all the files it generates during the build process. For example the Clover plugin will put instrumented sources somewhere inside this directory.
  • Type: java.lang.String
  • Required: Yes
  • Default: ${project.build.directory}/clover

cloveredArtifactExpiryInMillis:

The difference (in milliseconds) that a -clover classified artifact can have to a non-clover classified artifact.

If the -clover classified artifact is more than cloveredArtifactExpiryInMillis older than the non-clover classified artifact, then the non-classified artifact will be used.

This setting defaults to 2000.

  • Type: long
  • Required: No
  • User Property: maven.clover.cloveredArtifactExpiryInMillis
  • Default: 2000

copyExcludedFiles:

If set, then the maven-clover2-plugin will not copy files that were excluded, across to the target/clover directory. This is useful if the build is also using plugins such as the maven-gwt-plugin, that scans for resources, and skips a step if none are found. Otherwise, setting this to false could well cause build failures.
  • Type: boolean
  • Required: No
  • User Property: maven.clover.copyExcludedFiles
  • Default: true

debug:

If you wish to enable debug level logging in just the Clover plugin, set this to true. This is useful for integrating Clover into the build.
  • Type: boolean
  • Required: No
  • User Property: maven.clover.debug
  • Default: false

distributedCoverage:

The configuration for distributed coverage collection by Clover.

If present, default values will be used and coverage will be collected across JVMs.

Optional nested elements (and their defaults) of distributedCoverage are:

  • host - the host name of the JVM running the tests. default: localhost
  • port - the port that Clover can bind to in the host JVM. default: 1198
  • numClients - the number of clients expected to attach to the Test JVM. The test JVM will wait until numClients have connected before continuing. default: 0
  • timeout - the amount of time to wait for a response from a remote JVM before shunning it. default: 5000
  • retryPeriod - the amount of time a client should wait between reconnect attempts. default: 1000
  • Type: com.atlassian.maven.plugin.clover.DistributedCoverage
  • Required: No

encoding:

The character encoding to use when parsing source files.
  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.encoding

excludes:

The list of file to exclude from the instrumentation. Patterns are resolved against source roots.
  • Type: java.util.Set
  • Required: No

excludesList:

The comma seperated list of file to exclude from the instrumentation. Patterns are resolved against source roots.
  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.excludesList

flushInterval:

When the Clover Flush Policy is set to "interval" or threaded this value is the minimum period between flush operations (in milliseconds).
  • Type: int
  • Required: No
  • User Property: maven.clover.flushInterval
  • Default: 500

flushPolicy:

The Clover flush policy to use. Valid values are directed, interval and threaded.
  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.flushPolicy
  • Default: threaded

groverJar:

By default, Maven Clover Plugin generates the ${java.io.tmpdir}/grover*.jar file during setup, which is next being added as the dependent artifact to the build. As the file has generated, unique name and the jar is not being removed at the end of the build, these files can litter the temporary directory.

By setting this parameter you can:

a) specify constant file name for generated artifact,

b) choose location different than ${java.io.tmpdir}.

However, you must ensure that:

a) grover.jar will not be deleted till end of the build (for example don't put into ./target directory and next run mvn clover2:setup clean)

b) grover.jar will not be shared among builds with different Maven Clover Plugin versions used (for example if ProjectA uses Clover v 3.1.8 and ProjectB uses Clover v 3.1.9 then they shall have different groverJar locations defined)

  • Type: java.io.File
  • Since: 3.1.8
  • Required: No
  • User Property: maven.clover.groverJar

includes:

The list of file to include in the instrumentation. Patterns are resolved against source roots. Defaults are '**/*.java, **/*.groovy' which are overwritten if <includes> is set by the user
  • Type: java.util.Set
  • Required: No

includesAllSourceRoots:

Till 3.1.11: whether the Clover plugin should instrument all source roots (for example src/main/java, src/main/groovy, target/generated-sources, so including the generated sources) or whether it should only instrument the main source root (usually src/main/java).

Since 3.1.12: whether the Clover plugin should instrument all source roots (for example src/main/java, src/main/groovy, target/generated-sources, so including the generated sources) or whether it should instrument non-generated source roots (i.e. all roots except target/generated-sources/*)

  • Type: boolean
  • Required: No
  • User Property: maven.clover.includesAllSourceRoots
  • Default: false

includesList:

The comma seperated list of files to include in the instrumentation. Patterns are resolved against source roots. Defaults are **.java which are overwritten if <includes> is set by the user
  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.includesList

includesTestSourceRoots:

Whether the Clover plugin should instrument test source roots.
  • Type: boolean
  • Required: No
  • User Property: maven.clover.includesTestSourceRoots
  • Default: true

instrumentLambda:

Define whether lambda functions shall be instrumented: Valid values are:

  • none - do not instrument lambda functions (note: statements inside lambdas will become a part of a parent function)
  • expression - instrument only expression-like lambdas, e.g. (a,b) -> a + b
  • block - instrument block lambdas, e.g. () -> { foo(); }
  • all_but_reference - instrument lambdas written in any form except method references, e.g. Math::abs
  • all - instrument all forms of lambda functions

Default is 'all' for 3.2.2-4.0.2 and 'none' since 4.0.3.

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

  • Type: java.lang.String
  • Since: 3.2.2
  • Required: No
  • User Property: maven.clover.instrumentLambda
  • Default: none

instrumentation:

The level to instrument to. Valid values are 'method' or 'statement'. Default is 'statement'.

Setting this to 'method' greatly reduces the overhead of enabling Clover, however limited or no reporting is available. The current use of setting this to method is for Test Optimization only.

  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.instrumentation

jdk:

Which Java language level Clover shall use to parse sources. Valid values are:

  • 1.3
  • 1.4 (introduces 'assert' keyword)
  • 1.5 ('enum' keyword and generics)
  • 1.6 (no language changes)
  • 1.7 (String in switch, try with resources, binary literals, underscores in literals)
  • 1.8 (lambda expressions, default methods in interfaces)

By default Clover instruments using the highest language level supported.

  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.jdk

license:

The full Clover license String to use. If supplied, this certificate will be used over licenseLocation. NB. newline chars must be preserved. A trial Clover license can be generated here.
  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.license

licenseLocation:

A Clover license file to be used by the plugin. The plugin tries to resolve this parameter first as a resource, then as a URL, and then as a file location on the filesystem. A trial Clover license can be generated here.
  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.licenseLocation

methodContexts:

Specifies the custom method contexts to use for filtering specific methods from Clover reports.

e.g.
<main>public static void main\(String args\[\]\).*</main>

will define the context called 'main' which will match all public static void main methods.

  • Type: java.util.Map
  • Required: No

project:

The Maven project instance for the executing project.

Note: This is passed by Maven and must not be configured by the user.

  • Type: org.apache.maven.project.MavenProject
  • Required: Yes
  • User Property: project

repositoryPollutionProtection:

Try to protect your build from installing instrumented artifacts into local ~/.m2 cache or deploying them to a binaries repository. If this option is enabled, Clover will fail a build whenever it detects that 'install' or 'deploy' phase is about to be called. It will also fail a build if it detects that an artifact having multiple classifiers (e.g. "-clover-tests.jar"), which are not supported by Maven, is about to be installed under original name (e.g. "-tests.jar").

Please note that this flag may not protect from all possible cases.

  • Type: boolean
  • Since: 4.0.4
  • Required: No
  • User Property: maven.clover.repositoryPollutionProtection
  • Default: false

scope:

When creating the clover.jar dependency, what scope to use. This may be one of: compile, test, provided etc. If not specified - provided will be used.
  • Type: java.lang.String
  • Required: No
  • User Property: maven.clover.scope

setTestFailureIgnore:

If set to true, Clover will add several properties to the build configuration which disable a build failure for following plugins:

  • maven-surefire-plugin (maven.test.failure.ignore=true)
  • maven-failsafe-plugin (maven.test.failure.ignore=true)
  • maven-checkstyle-plugin (checkstyle.failOnViolation=false)
  • maven-pmd-plugin (pmd.failOnViolation=false)

Thanks to this, build continues despite test failures or code validation failures and thus it is possible to generate a Clover coverage report for failed tests at the end of the build.

Note: before version 3.1.9 the testFailureIgnore property was set to true for the forked Clover lifecycle ('instrument' goal) for 'test' and 'integration-test' phases. Since 3.1.9 it is no longer set.

  • Type: boolean
  • Since: 3.1.9
  • Required: No
  • User Property: maven.clover.setTestFailureIgnore
  • Default: false

singleCloverDatabase:

If true, then a single cloverDatabase will be used for the entire project. This flag will be ignored if a custom cloverDatabase location is specified.
  • Type: boolean
  • Required: No
  • User Property: maven.clover.singleCloverDatabase
  • Default: false

skip:

A flag to indicate not to run clover for this execution. If set to true, Clover will not be run.
  • Type: boolean
  • Required: No
  • User Property: maven.clover.skip
  • Default: false

skipGroverJar:

By default, Maven Clover Plugin generates the ${java.io.tmpdir}/grover*.jar file during setup, which is next being added as the dependent artifact to the build. As the file has generated, unique name and the jar is not being removed at the end of the build, these files can litter the temporary directory.

In case when there is no Groovy code in the project, this parameter can be set to true in order to disable generation of grover.jar artifact.

  • Type: boolean
  • Since: 3.1.8
  • Required: No
  • User Property: maven.clover.skipGroverJar
  • Default: false

snapshot:

The location to store the clover snapshot file. This file needs to persist between builds to enable Clover's build optimization feature. If not specified, the snapshot will be stored next to the cloverDatabase.
  • Type: java.io.File
  • Required: No
  • User Property: maven.clover.snapshot

staleMillis:

Sets the granularity in milliseconds of the last modification date for testing whether a source needs reinstrumentation.
  • Type: int
  • Required: No
  • User Property: maven.clover.staleMillis
  • Default: 0

statementContexts:

Specifies the custom statement contexts to use for filtering specific statements from Clover reports. e.g.
<log>^LOG\..*</log>
defines a statement context called "log" which matches all LOG statements.
  • Type: java.util.Map
  • Required: No

useCloverClassifier:

Whether or not to include the -clover classifier on artifacts.
  • Type: boolean
  • Required: No
  • User Property: maven.clover.useCloverClassifier
  • Default: true

useFullyQualifiedJavaLang:

Use the fully qualified package name for java.lang.* classes.
  • Type: boolean
  • Required: No
  • User Property: maven.clover.useFullyQualifiedJavaLang
  • Default: true

waitForFlush:

If true we'll wait 2*flushInterval to ensure coverage data is flushed to the Clover database before running any query on it.

Note: The only use case where you would want to turn this off is if you're running your tests in a separate JVM. In that case the coverage data will be flushed by default upon the JVM shutdown and there would be no need to wait for the data to be flushed. As we can't control whether users want to fork their tests or not, we're offering this parameter to them.

  • Type: boolean
  • Required: No
  • User Property: maven.clover.waitForFlush
  • Default: true