This page contains best practices for using Clover for Maven 2 and 3.

On this page:

Test Optimization in a CI Environment

There are two recommended ways to utilize Clover's test optimization in a CI (Continuous Integration) environment, either using a Profile, or to run the goals directly.
NB. Clover Test Optimization will not work if you have added the maven-clover2-plugin to the default build section of the pom with an execution binding the 'instrument' goal.

Setting up a CI Profile

1. Add a 'clover.optimize' profile to the project's pom.xml.
2. Create a new 'Gateway' build plan in your CI server. A 'Gateway' build plan is one that gets run before any others and if successful, triggers any subsequent builds.

3. The gateway plan should execute the verify phase, with the 'clover.optimize'profile activated. Example:

   mvn verify -Pclover.optimize
   

4. If your build plan is configured to do a full clean checkout before each build — you will need to ensure the Clover snapshot file is stored in a location that will not be removed between builds. The following configuration added to the pom.xmlis one option:

   <configuration>
     <snapshot>${user.home}/.clover/${groupId}-${artifactId}/clover.snapshot</snapshot>
   </configuration>
   

   Please note, if you are using a version of Clover for Maven 2 prior to 2.4.2, this directory must exist due to CLMVN-86.

5. Beware however, that this set up will instrument your source and test files and compile them to the usual Maven output location. If you run this command:

   mvn deploy -Pclover.optimize
   

   then you will be deploying class files that have been instrumented by Clover.

Running the Clover 2 goals Directly

Add a new build plan with the following command line:

mvn clover2:setup verify clover2:snapshot

Test Optimization on the Desktop

Running Clover's test optimization locally is very advantageous. This is achieved using the 'clover.optimize' profile that can be activated like so:

mvn verify -Pclover.optimize

Combining Build Optimization with Site Coverage Reporting

Maven2 will merge any executions defined in the default build section of the pom, with those defined in a profile. It is therefore recommended practice to always use two profiles — one for test optimization and one for generating a Clover report when you generate a site. The clover2:instrument goal forks the build lifecycle ensuring that Clover instrumented sources are kept completely separate from production sources. This also means that your tests get run twice — which is obviously not desirable in an optimized build.

The 'clover.report' profile is an example of a build profile to activate when running this command:

mvn site -Pclover.report

Using separate profiles for site generation and Test Optimization is currently the recommended way to have both a site and a Test Optimization Clover build configured in the same pom.xml.

Test Optimization across a Multimodule Project

By default, Clover will generate a new clover.db and clover.snapshot file for each module. This means, that if you have tests in module A that cover code in module B, and you modify code in module B, the tests in module A will not be run.

You can achieve the desired behaviour however, by configuring Clover to use a single clover.db and clover.snapshot for the entire project:

<configuration>
        <snapshot>${user.home}/.clover/atlassian-plugins-clover.snapshot</snapshot>
        <singleCloverDatabase>true</singleCloverDatabase>
</configuration>

If you have many modules, you may need to set fullBuildEvery to a value higher than the default of 10. See also singleCloverDatabase.

clover2:setup Non-forked Lifecycle

clover2:setup is a new MOJO designed to make integration with integration and functional tests a lot simpler than using the forked lifecycle that comes with clover2:instrument. It also has the added advantage of not having to run your tests twice.

Executing clover2:setup does the following:

• Instruments all source and test files found in src/main/java, src/test/java .
• Copies the instrumented source files to target/clover/src-optimized, target/clover/src-test-optimized respectively.
• Redirects the Maven project's source and test directories to target/clover/src-optimized, target/clover/src-test-optimized. Subsequent plugins in the build lifecycle then use these locations as the source directories.

Therefore, executing the following line will instrument all source and test files, compile the instrumented source files, run all tests and then install the compiled and instrumented classes.

$> mvn clover2:setup install clover2:clover

WARNING: It is not recommended to deploy your Clover instrumented classes to an external Maven repository.

clover2:setup will automatically bind itself to the 'process-sources' phase if defined in the goals list of the plugin's executions.

Cross Compilation using Groovy

If you are using cross-compilation with Groovy code, you should ensure that the maven-clover2-plugin:setup goal runs before the GMaven Plugin's gmaven:generateStubs goal in your pom.xml. Otherwise, you may end up with errors when running the Clover-for-Maven 2 plugin.

Alternatively, if you run clover2:setup directly from the mvn command line, then this Clover goal will run before the gmaven:generateStubs goal and you will avoid these errors when cross-compiling Groovy code.

Colouring Test Optimization

If your terminal supports ANSI escape codes, run your Maven build with the -Dansi.color flag. Currently a few important log messages dealing with Clover's Test Optimization will be logged in colour:

Screenshot: Coloured Text in Clover Log Messages

Build Profiles

The following profiles can be used directly in the pom.xml. This avoids the need to modify the ~/.m2/settings.xml file.

clover.report Profile

<profile>
            <id>clover.report</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.atlassian.maven.plugins</groupId>
                        <artifactId>maven-clover2-plugin</artifactId>
                        <version>${cloverVersion}</version>
                        <executions>
                            <execution>
                                <id>clover</id>
                                <phase>verify</phase>
                                <goals>
                                    <goal>instrument</goal>
                                    <goal>check</goal>
                                    <goal>clover</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
             <reporting>
                 <plugins>
                     <plugin>
                         <groupId>com.atlassian.maven.plugins</groupId>
                         <artifactId>maven-clover2-plugin</artifactId>
                         <version>${cloverVersion}</version>
                     </plugin>
                 </plugins>
             </reporting>
        </profile>

Clover Optimize Profile

<profile>
            <id>clover.optimize</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.atlassian.maven.plugins</groupId>
                        <artifactId>maven-clover2-plugin</artifactId>
                        <version>${cloverVersion}</version>
                        <configuration>
                              <snapshot>${user.home}/.clover/${groupId}-${artifactId}/clover.snapshot</snapshot>
                        </configuration>
                        <executions>
                            <execution>
                                <id>clover</id>
                                <goals>
                                    <goal>setup</goal>
                                    <goal>optimize</goal>
                                    <goal>snapshot</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>

Clover Optimize, Report, Log and Check Profile

<profile>
            <id>clover.all</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.atlassian.maven.plugins</groupId>
                        <artifactId>maven-clover2-plugin</artifactId>
                        <configuration>
                              <targetPercentage>93%</targetPercentage>
                              <snapshot>${user.home}/.clover/${groupId}-${artifactId}/clover.snapshot</snapshot>
                        </configuration>
                        <executions>
                            <execution>
                                <id>clover</id>
                                <goals>
                                    <goal>setup</goal>
                                    <goal>optimize</goal>
                                    <goal>snapshot</goal>
                                </goals>
                            </execution>
                            <execution>
                                <phase>verify</phase>
                                <goals>
                                    <goal>clover</goal>
                                    <goal>log</goal>
                                    <goal>check</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>

Related Links

• Overview of Test Optimization

• Test Optimization Technical Details

• Test Optimization Quick Start for Ant

• Test Optimization Quick Start for Maven 2 and 3