Enabling the Clover add-on
This page describes how to enable and configure Atlassian's Clover add-on for a job in Bamboo.
When Bamboo is integrated with Clover, you can:
- View code-coverage details (i.e. the percentage of code covered by tests) for each build result
- View code-coverage trends for a job over a period of time
- View the code-coverage summary for the job.
On this page:
Enable the Clover add-on
- Navigate to the desired job, as described on Configuring jobs.
- Choose Actions > Configure Job.
- Click the Miscellaneous tab.
Select Use Clover to collect Code Coverage for this build and set the following:
- Automatically integrate Clover into this build
You will need to provide a Clover license, unless this has been configured globally in the Administration panel (Administration > Plugins > Clover Plugin).
- Generate a Clover Historical Report
Displays the current coverage results compared with previous Clover code coverage reports.
- Generate a JSON report
Provides the Clover results in a format ready for embedding into applications or external report views.
- Use plan-defined Clover license key
Override the global Clover license for this particular plan.
- Clover is already integrated into this build
Use this option when you already have Clover-for-Ant, Clover-for-Maven or another Clover integration configured to generate a report.
Clover XML Location
Specify the location where Bamboo will look for the XML report file from Clover. Please specify the file path relative to your plan's root directory (e.g
/home/bamboouser/bamboo-home/xml-data/build-dir/MY_PLAN/), i.e. do not specify an absolute path.
- Automatically integrate Clover into this build
Screenshot: Settings to enable Clover for a job:
As Clover integration (automatic and manual) produces instrumented classes, we recommend that you ensure that your job does 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 locations is usually not desired.
Common practices to ensure proper separation of instrumented and non-instrumented classes are:
- create a dedicated plan or job with Clover integration enabled
- enable automatic Clover integration for jobs running tests only (e.g. "mvn verify")
- use different location of local artifact cache if you need to install artifacts (e.g. ~/.m2/repository-clover and "mvn install")
- use different URL for uploading artifacts if necessary (e.g. a separate repository for "mvn deploy")
Automatic Clover integration
Automatic integration works with Ant, Maven 2.x, Maven 3.x and Grails tasks:
- Check Use Clover to collect Code Coverage for this build in the Clover Code Coverage settings.
- Select Automatically integrate Clover into this build.
- Enter the global license key for Clover (go to Administration > Plugins > Clover Plugin), or enable Use plan-defined Clover license key and paste the key into the text field that appears.
Additionally, you can:
- Select Generate a Clover Historical Report to compare the current coverage results with previous Clover code coverage reports.
- Select Generate a JSON report to get the Clover results in a format ready for embedding into applications or external report views.
Behavior of automatic integration has changed in Bamboo 5.9
Automatic Clover integration for Maven 2 and Maven 3 tasks has been improved in Bamboo 5.9. It became tighter and now it adds Clover goals between goals from the original command in such way that a build is performed only once. It does not run "clean" and "verify" separately any more. Thanks to this, builds with automatic Clover integration may be as twice as fast.
In order to protect you against publishing instrumented code, automatic Clover integration will not run if the Maven task runs the "install" or "deploy" phases. In such case, you will find no Clover report and a build log will contain an appropriate warning message. In order to get coverage reports for such job, either edit the Maven task to run the build till the "verify" phase (or earlier) or configure Clover manually.
Automatic Clover integration before Bamboo 5.9 was adding Clover goals at the end of the original Maven command. As a consequence, build was performed twice (first - original goals/phases, next - with Clover enabled and the "verify" phase), which had it's advantages (better, but not full, separation of instrumented and non-instrumented code) and drawbacks (build times as twice as long, problems with artifact dependencies in maven-surefire-plugin or maven-assembly-plugin as described in BAM-13208).
When automatic Clover integration is enabled, Bamboo:
- Creates an artifact named Clover Report (System), which is visible on the 'Artifacts' tab for the job.
and during every build:
- Extracts the Clover license (either the global or plan license key) into a temporary file and passes it to:
- an Ant task as -Dclover.license.path=/<bamboo-home>/xml-data/build-dir/<your-job>/.clover/clover.license
- a Maven task as -Dmaven.clover.licenseLocation=/<bamboo-home>/xml-data/build-dir/<your-job>/.clover/clover.license
- Enhances tasks by adding
- Ant - targets like "with.clover", "clover.report"
- Maven - goals like "clover2:setup", "clover2:aggregate", "clover2:clover", "clover2:save-history"; it also adds "verify" phase if original command does not call "compile" or later phase
- Grails - options like "-clover.on"
- Generates Clover XML and HTML reports (by default)
- Generates statistics and charts for a plan summary
Manual Clover integration
Manual Clover integration works with any kind of task in which Clover can be called (Ant, Maven 2.x, Maven 3.x, Command, Grails).
- Check Use Clover to collect Code Coverage for this build, in the Clover Code Coverage settings.
- Check Clover is already integrated into this build ...
- Specify in where Bamboo will look for the XML report file generated by Clover.
On the 'Artifacts' tab, click Create Definition and complete the form as follows:
This should begin with with "Clover Report".
This should point to the HTML report directory (e.g. target/site/clover)
Configure Clover in your build script so that it generates both XML and HTML reports.Example for Ant...
<clover-report initstring="target/clover/database/clover.db"> <current outfile="target/site/clover/clover.xml" /> <current outfile="target/site/clover"> <format type="html"/> </current> </clover-report>Example for Maven...
<plugin> <groupId>com.atlassian.maven.plugins</groupId> <artifactId>maven-clover2-plugin</artifactId> <configuration> <generateHtml>true</generateHtml> <generateXml>true</generateXml> </configuration> </plugin>
Configure the Clover license in your build script or pass it as a proper task parameter in the job configuration:
How to declare the license location in pom.xml...
- Save the Clover license key in a file (for example in /opt/bamboo/clover.license).
- Pass the location of the license key to the build task:
- Define it in the build script, or
- Pass it as a Java property for the Ant/Maven task in the plan configuration.
<plugin> <groupId>com.atlassian.maven.plugins</groupId> <artifactId>maven-clover2-plugin</artifactId> <version>3.1.8</version> <configuration> <licenseLocation>/opt/bamboo/clover.license</licenseLocation> <generateXml>true</generateXml> <generateHtml>true</generateHtml> </configuration> </plugin>How to declare the license location in build.xml...
<project> <property name="clover.license.path" location="/opt/bamboo/clover.license"/> <!-- ... --> </project>How to pass the license location for Ant...
clean with.clover test clover.report -Dclover.license.path=/opt/bamboo/clover.licenseHow to pass the license location for Maven...
mvn clean clover2:setup verify clover2:aggregate clover2:clover -Dmaven.clover.licenseLocation=/opt/bamboo/clover.license
After every build, Bamboo will parse the Clover XML file and generate statistics and charts for a plan summary. The Plan summary and job summary pages will contain a "Clover" tab.
Browsing Clover results
Clover HTML report and Clover statistics for a job: see Viewing the Clover code-coverage for a plan.
Clover code coverage summary for a plan: see Viewing the Clover code-coverage for a build.
Clover code coverage statistics across multiple plans: see Generating reports across multiple plans.
Limit the machines that Clover runs on
- For each of the EC2 images on which you would like to run builds with Clover, add a capability such as "clover=true" to the configuration for the image.
To do this, go to Administration > Elastic Bamboo > Configuration. Select the elastic image and click Add Capability.
- Now, add a matching requirement, such as "clover=true", to the configuration for each job.
To do this, go to Actions > Configure Plan > Jobs. Select the job where Clover runs and click Requirements and then Add Extra Requirement.
Automatic or manual Clover integration and spawned processes
Using automatic Clover integration or adding a dependency to the maven-clover2-plugin manually is usually sufficient.
However, if your build spawns another JVM process (for example: unit tests executed in a forked JVM, tests in the container instantiated on the fly, tests calling code deployed on another server), you must manually add the dependency to the Clover JAR for these spawned processes.
See NoClassDefFoundError com_atlassian_clover/CoverageRecorder KB article.
Automatic Clover integration and building in a subdirectory
In case you perform a build in a subdirectory (for instance, in the Maven Task configuration you have the "Working sub directory" field set) and you have automatic Clover integration, you may need to correct the Location in the "Clover Report (System)" artifact. Otherwise, an HTML report may be empty as automatic Clover integration uses the default path (for instance, the "target/site/clover" in case of integration with Maven).
This issue has been fixed in Bamboo 5.7.
Automatic Clover integration and multi-module Maven projects
If you have a multi-module Maven project with dependencies between modules and use Automatic Clover integration, it can happen that an instrumented JAR of the dependent artifact will be taken for test execution in a build phase where Clover was not enabled yet. See BAM-13208 for more details. In such case, we recommend the following:
- create a separate Job in which automatic Clover integration is enabled
- create a Maven task in this job, which will do nothing (call the "clean" goal, for instance)
- Bamboo will automatically add Clover-related goals (clover2:setup verify clover2:aggregate clover2:clover)
This issue has been fixed in Bamboo 5.9.
Clover Results Collector is unable to find the XML report file
In the build log you may see a warning like:
Failed to execute plugin 'Clover Results Collector' with error: No file matches the specified pattern ...
The are several possible reasons, see this article for more details: Failed to execute plugin 'Clover Results Collector'.