Basic usage
Configuring Clover's short name in .m2/settings.xml
Before you get started, add this to your .m2/settings.xml file so you can reference Clover by its short name clover.
<pluginGroups>
<pluginGroup>com.atlassian.maven.plugins</pluginGroup>
</pluginGroups>
Running Clover goals from the command line
The quickest and easiest way to try Clover is from the command line, for example:
mvn clean clover:setup test clover:aggregate clover:clover
Installing Clover in pom.xml
Install Clover-for-Maven 2 and 3 by adding it to your Maven build file (pom.xml):
Set up your pom.xml by adding:
pom.xml<build> <plugins> ... <plugin> <groupId>com.atlassian.maven.plugins</groupId> <artifactId>clover-maven-plugin</artifactId> <version>${clover.version}</version> <configuration> <licenseLocation>/path/to/clover.license</licenseLocation> </configuration> </plugin> ... </plugins> </build>
Either change ${clover.version} to the current Clover version, or define a property in your pom.xml that sets this value.
Clover ships with a 30 day evaluation license. After 30 days you need a valid Clover license file to run Clover. You can obtain a free 30 day evaluation license or purchase a commercial license at http://my.atlassian.com. You will need to set up your license, as a <licenseLocation>element in yourpom.xmlconfiguration file.Now, simply invoke Clover with Maven on the command line.
mvn clean clover:setup test clover:aggregate clover:cloverThis will instrument your sources, build your project, run your tests and create a Clover coverage report in the target/site/clover directory.
You can also have Clover run as part of your build by adding Clover's goals in pom.xml.
There are four basic parts executed when recording code coverage with Clover.
- The clover:setup goal will instrument your Java source files.
- The test phase is Maven 2 and 3's standard command for running a unit test phase.
- The clover:aggregate goal is used for merging coverage data generated by multi-module projects.
- The clover:clover goal generates an HTML, XML, PDF or JSON report.
Running Goals via pom.xml
The goals described above can be executed by specifying them in your pom.xml.
To generate a Clover report when you run the site goal:
<project>
...
<reporting>
<plugins>
...
<plugin>
<groupId>com.atlassian.maven.plugins</groupId>
<artifactId>clover-maven-plugin</artifactId>
<configuration>
...
</configuration>
</plugin>
</plugins>
</reporting>
...
To instrument your sources whenever you build:
<project>
...
<build>
<plugins>
<plugin>
<groupId>com.atlassian.maven.plugins</groupId>
<artifactId>clover-maven-plugin</artifactId>
<configuration>
...
</configuration>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>instrument</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
To include aggregation of child modules:
<project>
...
<build>
<plugins>
<plugin>
...
<executions>
<execution>
<id>main</id>
<phase>verify</phase>
<goals>
<goal>instrument</goal>
<goal>aggregate</goal>
</goals>
</execution>
<execution>
<id>site</id>
<phase>pre-site</phase>
<goals>
<goal>instrument</goal>
<goal>aggregate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
...
Using clover:setup vs clover:instrument vs clover:instrument-test
The clover:setup goal performs instrumentation in the main build life cycle, therefore it's not recommended to use it together with 'install' or 'deploy' goals (unless this is your intention). The benefit of this approach is that build is made only once. Furthermore, clover:setup supports instrumentation of Groovy code (while clover:instrument does not).
The clover:instrument goal can be used if you need to actually install or deploy non-instrumented project's artifact and have Clover run at the same time. This will fork a custom build life cycle and run it till the "verify" phase and cause each Clover artifact to contain the -clover classifier. A drawback of this approach is that the build and tests are performed twice.
This goal has one limitation - due to a fact that Maven allows to have only one classifier for an artifact, the 'clover' suffix may not be added if you use own classifiers. It means that it can happen that instrumented code (e.g. myapp-1.0-tests-clover.jar) will be installed using its original name (e.g. myapp-1.0-tests.jar). Using maven-install-plugin with <installAtEnd>true</installAtEnd> may help as it re-installs non-instrumented JARs at the end of the build.
The clover:instrument-test goal also forks a custom build cycle, but runs it till the "test" phase. Thanks to this, instrumented artifacts are not installed.
How to manage instrumented code
As Clover integration produces instrumented classes, we recommend to ensure that you do not install them to production (for instance: 'mvn deploy' to public repository, 'scp' to an application server running on production, etc). Having instrumented code in such location(s) is usually not desired.
Common practices to ensure proper separation of instrumented and non-instrumented classes and JARs are:
- configure Clover in a profile in your pom.xml
- create a dedicated build plan in which Clover is enabled
- use clover:setup to run tests only (e.g. "mvn test" or "mvn verify")
- in case you must run "mvn install", use different location of local artifact cache (e.g. ~/.m2/repository-clover)
- in case you must run "mvn deploy", use different URL for uploading artifacts (i.e. a separate binary repository)
- use clover:instrument or clover:instrument-test if you need to produce both instrumented and non-instrumented code
- keep in mind that Maven does not support multiple classifiers for an artifact