GitLab CI artifacts:reports: JUnit Test Results and Code Coverage in the Merge Request Widget

1. Why a Plain Exit Code Is Not Enough

A test job in GitLab CI is considered successful as soon as the executed command returns exit code 0, and failed for any other code. This binary piece of information is enough for a rough go or no go decision, but it reveals nothing about which individual tests failed, how long they took, or whether a new change made test coverage worse. Anyone wanting to see these details has so far had to search through the full job logs, which quickly becomes impractical for large test suites with thousands of individual tests.

GitLab's report artifacts solve this by specifically collecting structured output files from the test run and rendering them in the GitLab UI. artifacts:reports:junit processes the industry standard JUnit XML format and shows individual test results directly in the merge request widget, while artifacts:reports:coverage_report reads coverage data in Cobertura format and generates both an overall percentage and colored line markers in the diff view from it. Both mechanisms require the test output to be in the correct format, which for PHPUnit requires deliberate configuration.

2. artifacts:reports:junit: Understanding the JUnit XML Format

The JUnit XML format originally comes from the Java ecosystem, but is nowadays supported by virtually every popular test framework, including PHPUnit for PHP and Jest or Mocha for Node.js. It describes every individual test class as a testsuite element with nested testcase elements, each carrying a name, a runtime, and in the case of a failure a failure or error child element including a stack trace. GitLab parses this structure and displays it in the merge request widget as an expandable list, with failed tests highlighted and shown at the top.

Particularly valuable is the automatic detection of newly failing tests compared to ones that already failed before: GitLab compares the merge request's JUnit result against the target branch's and explicitly marks which tests newly broke because of the current change, as opposed to already known, longer standing failures. This saves reviewers the tedious manual research of whether a red test was actually caused by the current merge request or was already failing before it.

# .gitlab-ci.yml
phpunit:
  stage: test
  script:
    - vendor/bin/phpunit --log-junit report.xml
  artifacts:
    when: always
    reports:
      junit: report.xml

3. Configuring PHPUnit for JUnit Output

PHPUnit produces the JUnit XML format via the command line parameter --log-junit followed by the target file path, which is entirely sufficient for a simple integration. For projects that control their PHPUnit configuration through a phpunit.xml file rather than command line parameters, the same effect can be achieved through the logging element inside that file, which has the advantage of keeping the configuration versioned in the repository instead of implicitly scattered across CI scripts.

The artifacts:when: always setting matters here, because without it the artifact only gets uploaded when the job exits successfully. Exactly when tests fail and the exit code is non zero, the JUnit report would not be available without this setting, even though the information about the failing tests is most valuable precisely at that moment. This pitfall frequently causes the merge request widget to remain empty on failed tests, even though the JUnit configuration looks correct at first glance.

<!-- phpunit.xml -->
<phpunit>
  <logging>
    <junit outputFile="report.xml"/>
  </logging>
</phpunit>

4. Setting Up artifacts:reports:coverage_report for Code Coverage

While junit maps individual test results, coverage_report deals with overall code coverage. GitLab expects the Cobertura XML format for this, which is likewise an industry standard and can be generated by PHPUnit through the coverage extension Xdebug or PCOV. Configuration happens in the artifacts:reports block under the coverage_report key, where both the path to the XML file and the path_type Cobertura need to be specified so GitLab interprets the format correctly.

For PHPUnit itself, a coverage element with a clover or cobertura report is additionally needed in phpunit.xml, with Cobertura directly delivering the format GitLab expects and therefore representing the simpler path. Without an installed coverage extension such as Xdebug or PCOV in the test container, the coverage report either stays empty or the job fails with an error, which is a common first stumbling block during setup, especially in slim Docker images that deliberately omit Xdebug to make test execution faster.

# .gitlab-ci.yml
phpunit:
  stage: test
  variables:
    XDEBUG_MODE: coverage
  script:
    - vendor/bin/phpunit --log-junit report.xml --coverage-cobertura coverage.xml
  artifacts:
    when: always
    reports:
      junit: report.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

5. Showing the Overall Coverage Percentage as a Pipeline Badge

In addition to the structured coverage_report, GitLab offers the Test coverage parsing project setting, where a regular expression can be stored that extracts the overall coverage percentage as text directly from the job logs and shows it as a badge on the pipeline overview page as well as a repository badge. For PHPUnit, an expression like Lines:\s*\d+\.\d+\% works well, matching the line produced by PHPUnit's text output, provided PHPUnit runs with the additional --coverage-text parameter.

This text based extraction is independent of the structured coverage_report and can even be used without it, but it only covers the aggregated overall percentage, not the line accurate view in the diff. In practice both usually pay off together: the regex for the quickly visible badge on the project overview, and the structured coverage_report for the detailed, line based view directly in the merge request diff, where reviewers can immediately see which newly added lines are actually covered by a test.

# .gitlab-ci.yml
phpunit:
  script:
    - vendor/bin/phpunit --coverage-text --colors=never
  coverage: '/^\s*Lines:\s*\d+\.\d+\%/'

6. How the Results Are Displayed in the Merge Request Widget

When a JUnit report is present, the merge request widget shows a compact summary with the total number of tests, the number of failures and their runtime, expandable down to individual failing test cases including their stack trace, without reviewers having to open the full job logs. When a coverage_report is present, GitLab adds colored margin markers to the diff view: green for newly added lines covered by tests, red for uncovered lines, pointing specifically to where a change was introduced without an accompanying test.

This visual feedback directly inside the code review context is considerably more effective than a plain overall coverage percentage, because it points precisely at the lines that actually changed, instead of delivering an abstract, project wide metric that can easily hide new, untested lines within a large, otherwise well tested codebase. A reviewer can see at a glance whether exactly the newly introduced business logic was actually tested, regardless of how high the project's overall coverage happens to be.

7. Enforcing Coverage Thresholds as a Quality Gate

Through the Merge request approvals project setting, rules can be defined that block a merge if coverage falls below a defined threshold or drops compared to the target branch. For PHPUnit projects, a separate job that parses the Cobertura file and explicitly fails with exit 1 when a minimum value is not met tends to work well, and integrates cleanly with existing rules conditions, for example to only apply on merge requests against main.

A realistic sense of proportion matters here: an overly high global threshold quickly leads developers to write tests just to hit the number, instead of covering genuinely meaningful cases. A more pragmatic approach is to insist primarily that coverage does not drop through a given merge request, rather than enforcing an absolute threshold, combined with targeted, higher requirements for newly written, security relevant code.

8. Outlook: JUnit and Coverage for Other Languages and Frameworks

The JUnit and Cobertura formats are deliberately designed to be language agnostic, which is why the same GitLab configuration works unchanged for other test frameworks, as long as they support a compatible output format. Jest for JavaScript produces JUnit XML through the jest-junit reporter, Node coverage can be output in Cobertura format either through the nyc package or Jest's built in coverage feature, while Go tests follow the same path through go-junit-report and gocover-cobertura.

For teams with mixed technology stacks, this means the once learned GitLab report configuration is reusable across project boundaries, regardless of the programming language involved. This considerably reduces the ramp up effort for new projects, since only the language specific tool for producing the JUnit or Cobertura file needs to be swapped out, while the GitLab side artifacts:reports configuration stays structurally identical.

9. Best Practices and a Format Comparison

A solid approach to reports starts with artifacts:when: always, so failed test jobs reliably upload their reports too, followed by a deliberate decision on whether to also maintain a text regex for the quick badge in addition to the structured coverage_report. For new projects it pays off to set up both report types from the start, rather than retrofitting them later once the test suite has already grown considerably and fixes become more effortful.

The table below compares the relevant report formats and their respective role in the GitLab context, to help quickly pick the right combination when setting things up for a concrete project, without having to try out every format individually.

10. Summary

11. FAQ: GitLab JUnit and Coverage Reports: Key Takeaways