JaCoCo Coverage Reports

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

• Introduced in GitLab 17.3 with a flag named jacoco_coverage_reports. Disabled by default.
• Generally available in GitLab 17.6. Feature flag jacoco_coverage_reports removed.

Leave your feedback

For JaCoCo coverage reports to work, you must generate a properly formatted JaCoCo XML file that provides line coverage.

The JaCoCo coverage reports visualization supports:

• Instructions (C0 Coverage), ci (covered instructions) in reports.

Add JaCoCo coverage job

To configure your pipeline to generate the coverage reports, add a job to your .gitlab-ci.yml file. For example:

Below is an example configuration:

test-jdk11:
  stage: test
  image: maven:3.6.3-jdk-11
  script:
    - mvn $MAVEN_CLI_OPTS clean org.jacoco:jacoco-maven-plugin:prepare-agent test jacoco:report
  artifacts:
    reports:
      coverage_report:
        coverage_format: jacoco
        path: target/site/jacoco/jacoco.xml

In this example, the mvn command generates the JaCoCo coverage report. The path points to the generated report.

If the job generates multiple reports, use a wildcard in the artifact path

Relative File Paths Correction

File path conversion

JaCoCo reports provide relative file paths but coverage report visualizations require absolute paths. GitLab attempts to convert the relative paths to absolute paths, using data from the related merge requests.

The path matching process is:

1. Find all the merge requests for the same pipeline ref.
2. For all the files that changed, find all the absolute paths.
3. For each relative path in the report, use the first matching absolute path.

This process might not always be able to find a suitable matching absolute path.

Multiple modules or source directories

With identical file names for multiple modules or source directories, it might not be possible to find the absolute path by default.

For example, GitLab cannot find the absolute paths if these files are changed in a merge request:

• src/main/java/org/acme/DemoExample.java
• src/main/other-module/org/acme/DemoExample.java

For path conversion to succeed, you must have some unique difference in the relative paths. For example, you can change one of the file or directory names:

• Change the filename:

  src/main/java/org/acme/DemoExample.java
  - src/main/other-module/org/acme/DemoExample.java
  + src/main/other-module/org/acme/OtherDemoExample.java

• Change the path:

  src/main/java/org/acme/DemoExample.java
  - src/main/other-module/org/acme/DemoExample.java
  + src/main/other-module/org/other-acme/DemoExample.java

You can also add a new directory, as long as the complete relative path is unique.

Troubleshooting

Metrics do not display for all changed files

Metrics might not display correctly if you create a new merge request from the same source branch, but with a different target branch.

The job doesn't consider the diffs from the new merge request and doesn't display any metrics for files not contained in the diff of the other merge request. This happens even when the generated coverage report contain metrics for the specified file.

To fix this issue, wait until the new merge request is created, then rerun your pipeline or start a new one. Then the new merge request is taken into account.