jacoco-plugin

A plugin for Jenkins to capture and visualize code coverage testing results for projects using the JaCoCo for code-coverage analysis.

More information can be found on the Wiki page https://wiki.jenkins-ci.org/display/JENKINS/JaCoCo+Plugin

Note: Version 2.0.0 and higher requires using JaCoCo 0.7.5 or newer, if your projects still use JaCoCo 0.7.4, the plugin will not display any code-coverage numbers any more! In this case please use version 1.0.19 until you can update jacoco in your codebase.

Looking for ways to contribute?

When looking for things to work at there are pull requests and a list of Jenkins Issues.

Discussion list

There is a developer list at https://groups.google.com/forum/#!forum/jenkins-jacoco-plugin-mailing-list, it is usually very low volume.

Contributing to the Plugin

Plugin source code is hosted on GitHub.

New feature proposals and bug fix proposals should be submitted as GitHub pull requests.

Fork the repository on GitHub, prepare your change on your forked copy, and submit a pull request (see here for open pull requests). Your pull request will be evaluated by this job.

Before submitting your change, please assure that you've added a test which verifies your change. There have been many developers involved in the jacoco plugin and there are many, many users who depend on the jacoco-plugin. Tests help us assure that we're delivering a reliable plugin, and that we've communicated our intent to other developers in a way that they can detect when they run tests.

Code coverage reporting is available as a maven target and is actively monitored. Please try your best to improve code coverage with tests when you submit.

Before submitting your change, please review the findbugs output to assure that you haven't introduced new findbugs warnings.

How to build and test

Build the plugin:

mvn package

Test locally (invokes a local Jenkins instance with the plugin installed):

mvn hpi:run

See https://jenkinsci.github.io/maven-hpi-plugin/ for details.

How to release a new version

Rolling a release requires you to set up a few additional things:

Run with Java 8 to not push code compiled with a newer version of Java
Github authentication should work via SSH, Username used should bet "git", it should use one of the local private SSH keys which should be uploaded to Github, see https://github.com/settings/keys, test via

ssh -vT git@github.com
Jenkins-CI authentication should work via settings in ~/.m2/settings.xml, see http://maven.apache.org/guides/mini/guide-encryption.html for details
The mvn-calls below should not require "username" and "password"
Check that all tests pass ("mvn findbugs:check" and "mvn checkstyle::check" report violations but are not blocking releases for now...)

mvn clean package && mvn validate
Manually test the plugin

mvn hpi:run

Go to http://localhost:8080/jenkins/ and perform some testing
Prepare the release

mvn release:prepare -DskipTests
Roll the release

mvn release:perform -DskipTests -Darguments="-DskipTests"
Update release notes at https://github.com/jenkinsci/jacoco-plugin/releases
Release should be visible immediately at https://repo.jenkins-ci.org/releases/org/jenkins-ci/plugins/jacoco/
Release is published after some time at https://mvnrepository.com/artifact/org.jenkins-ci.plugins/jacoco?repo=jenkins-releases

See also general documentation about releasing Jenkins plugins:

Current documentation: https://www.jenkins.io/doc/developer/publishing/requesting-hosting/
Maven Release Plugin: http://maven.apache.org/maven-release/maven-release-plugin/usage.html
The following are slightly outdated, but still contain some useful information
- https://wiki.jenkins.io/display/JENKINS/Hosting+Plugins#HostingPlugins-Requestuploadpermissions
- https://wiki.jenkins.io/display/JENKINS/Hosting+Plugins#HostingPlugins-Releasingtojenkins-ci.org

Basic information

Repository address: https://github.com/jenkinsci/jacoco-plugin/
Mailing list: http://groups.google.com/group/jenkins-jacoco-plugin-mailing-list
Issue tracking: https://issues.jenkins-ci.org/browse/JENKINS/
Build and test results: https://jenkins.ci.cloudbees.com/job/plugins/job/jacoco-plugin/

This plugin allows you to capture code coverage report from JaCoCo. Jenkins will generate the trend report of coverage and some other statistics.

It also includes functionality to include columns in Dashboards which displays the latest overall coverage numbers and links to the coverage report.

Getting Started

The plugin provides two things, a build-publisher to record and display coverage data as part of builds as well as a new column-type for dashboard views which can display coverage data in Dashboards.

Recording coverage for builds

Get coverage data as part of your build

First you need to get coverage calculated as part of your build/tests, see the JaCoCo documentation
for details. You need at least one or more *.exec file available after tests are executed. Usually this means adjusting
your Maven pom.xml or Ant build.xml file..

Set up coverage retrieval and publishing

In order to get the coverage data published to Jenkins, you need to add a JaCoCo publisher and configure it so it will
find all the necessary information. Use the help provided via the question-mark links for more information. Basically
you specify where the *.exec files are, where compiled code can be found and where the corresponding source code is
located after the build is finished to let the plugin gather all necessary pieces of information..

Run the job

After the job executed, the build-output will show that the JaCoCo-publisher is executed and collects the data. This
output can also give hints if something goes wrong at this stage:

Zeichne Testergebnisse auf.
[JaCoCo plugin] Collecting JaCoCo coverage data...
[JaCoCo plugin] build/*.exec;build/*-classes;src/java,src/*/java,src/*/src; locations are configured
[JaCoCo plugin] Number of found exec files: 5
[JaCoCo plugin] Saving matched execfiles:  .../build/jacoco-excelant.exec .../build/jacoco-main.exec .../build/jacoco-ooxml-lite.exec
[JaCoCo plugin] Saving matched class directories:  .../build/examples-classes .../build/excelant-classes .../build/excelant-test-classes
[JaCoCo plugin] Saving matched source directories:  .../src/contrib/src .../src/examples/src .../src/excelant/java .../src/java
[JaCoCo plugin] Loading inclusions files..
[JaCoCo plugin] inclusions: []
[JaCoCo plugin] exclusions: [**/Test*]
[JaCoCo plugin] Thresholds: JacocoHealthReportThresholds [minClass=0, maxClass=0, minMethod=0, maxMethod=0, minLine=0, maxLine=0,
minBranch=0, maxBranch=0, minInstruction=0, maxInstruction=0, minComplexity=0, maxComplexity=0]
[JaCoCo plugin] Publishing the results..
[JaCoCo plugin] Loading packages..
[JaCoCo plugin] Done.

Look at results

If data gathering is successful, the build will include a link to the coverage results similar to the HTML report of
JaCoCo itself. The job page will be enhanced with a chart with the trend of code coverage over the last builds.

Coverage column

This part of the JaCoCo plugin allows you to add a new type of column to a project-table in the Dashboard view which
will show the coverage number of the last build for ajob together with some color coding which allows to quickly see
projects with low coverage.

The fill-color in use by the column is a continuous color-range with the following points:

PERFECT = 100.0
EXCELLENT at 97.0
GOOD at 92.0
SUFFICIENT at 85.0
FAIR at 75.0
POOR at 50.0
TRAGIC at 25.0
ABYSSMAL at 0.0
NA = No coverage configured

Open Tickets (bugs and feature requests)

See the Jenkins JIRA

Build Status

Troubleshooting

Unfortunately JaCoCo 0.7.5 breaks compatibility to previous binary formats of the jacoco.exec files. The JaCoCo plugin up to version 1.0.19 is based on JaCoCo 0.7.4, thus you cannot use this version with projects which already use JaCoCo 0.7.5 or newer. JaCoCo plugin starting with version 2.0.0 uses JaCoCo 0.7.5 and thus requires also this version to be used in your projects. Please stick to JaCoCo plugin 1.0.19 or lower if you still use JaCoCo 0.7.4 or lower

Change Log

Version 3.1.1-SNAPSHOT (unreleased)

Version 3.1.0 (Nov 13, 2020)

Update to JaCoco 0.8.6 to add support for JDK 15
Require minimum Jenkins version 2.164.3
Update some other third-party dependencies

Version 3.0.8 (Sep 17, 2020)

Add LICENSE file
JENKINS-58184 - Do not check coverage increase against the configured threshold
Bump Ant to 1.9.15

Version 3.0.7 (Jun 22, 2020)

Do not fail if tests are run without argLine
Update dependencies

Version 3.0.6 (May 29, 2020)

Add wiki content to main README
Adjust URLs in pom.xml
Ignore one test which is depending on the exact version of Java

Version 3.0.5 (January 25, 2020)

Initial support for JDK 11
JENKINS-49351: Added runAlways user paramater to allow Jacoco to run even if build FAILED or was ABORTED
JENKINS-56918: Adjust default source-includes to include *.groovy, *.kt and *.kts (Kotlin)
JENKINS-55166: Replace non-ASCII characters in properties for German and Spanish to not depend on the encoding of file

Version 3.0.4 (November 4, 2018)

PR #100/PR #102/JENKINS-49823 - Ignore non existing class directory
PR #101 - Add Branch Coverage Column

Version 3.0.3 (August 31, 2018)

Update JaCoCo to 0.8.2 to support Java 10 (``#99)
Update some other plugins
JENKINS-43310 add source file inclusions and exclusions (#85 / JENKINS-43310)

Version 3.0.2 (February 18, 2018)

No change upload due to problems with the release-workflow

Version 3.0.1 (February 18, 2018)

No change upload due to problems with the release-workflow

Version 3.0 (February 18, 2018)

Use the formatted date instead of the Calendar as the key to get the correct coverage trend per day ( #88)
Handle build abort (by not catching InterruptedException) (#86)
Improve exception handling (#89)
Update min Java version to Java 8, update Maven dependencies and plugins (#92)
Fix Javadoc warnings (#93)

Version 2.2.1 (May 5, 2017)

JENKINS-43103 Removed dependency on Joda Time
#83 Added symbol name for better pipeline integration
JENKINS-41515 Update Jenkins parent to 1.625.3 to be able to test with current pipeline-plugin
JENKINS-41515 Adjust dependencies and add some exclusions to remove a number of unnecessary jars from the resulting hpi file

Version 2.2.0 (Mar 22, 2017)

Configuration: Put checkboxes on top of threshold values in the configuration UI
#81 New flag to enable/disable display of source files with line coverage highlights
#80 Allow to fail the build if coverage degrades to much compared to previous build
#79/JENKINS-25076/JENKINS-29117 Report 100% for empty Coverage objects
#78/JENKINS-26254 Use BufferedInputStream to read .exec files
#76 Allow usage of environment variables in threshold fields.
JENKINS-38604: Limit copying of files to types *.java and *.class
JENKINS-36571: Update to Java 1.7
JENKINS-36536: Put a trend graph on the pipeline project page
JENKINS-32847: Add warning for sub directory filter
JENKINS-16787: Add shape and center plot for single-build-graphs

Version 2.1.0 (Sep 29, 2016)

JENKINS-16580 Display more than only line coverage in graph, #50
JENKINS-27120 Adding Workflow support for JaCoCo publisher, make JacocoPublisher a SimpleBuildStep, #63, #66, #70, #72, #73
Handle Jenkins publisher case when classes directory is empty, #67
JENKINS-32717 Multiple class directories and source directories not parsed if there is a space after comma delimiter, #68
Use full precision when comparing coverage to thresholds, #71
Expand the inclusion and exclusion inputs, #74

Version 2.0.1 (Jan 15, 2016)

Fix the m2e lifecycle-mapping, #64
Integrate automated builds via travis-ci and show the build-state on the github page
Fix for JENKINS-31751 JaCoCo 2.0.0 plugin shows html instead of coverage report chart

Version 2.0.0 (Nov 23, 2015)

Major version change because the jacoco.exec file from the newer JaCoCo is binary incompatible with previous builds
Update to JaCoCo 0.7.5, this causes binary incompatibility! See #55
Add coverage summary on build status/result page. Thanks to Felipe Brandão for the patch, see #61

Older changelog

Version 1.0.19 (Apr 7, 2015)

Update used version of JaCoCo to 0.7.4

Version 1.0.18 (Dec 7, 2014)

Fix JENKINS-23708 NullPointerException if older JaCoCo reports are opened

Version 1.0.17 (Nov 25, 2014)

Version 1.0.16 (Jun 24, 2014)

Fix [JENKINS-23426] - Crash publishing jacoco report across all projects - #44 - set dependency of asm to 5.0.1

Version 1.0.15 (Jun 11, 2014)

Version 1.0.14 (Nov 9, 2013)

Core JaCoCo plugin

Version 1.0.13 (Aug 22, 2013)