Unit test reports

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Unit test reports display test results directly in merge requests and pipeline details, so you can identify failures without searching through job logs.

Use unit test reports when you want to:

  • See test failures immediately in merge requests.
  • Compare test results between branches.
  • Debug failing tests with error details and screenshots.
  • Track test failure patterns over time.

Unit test reports require the JUnit XML format and do not affect job status. To make a job fail when tests fail, your job’s script must exit with a non-zero status.

GitLab Runner uploads your test results in JUnit XML format as artifacts. When you go to a merge request, your test results are compared between the source branch (head) and target branch (base) to show what changed.

File format and size limits

Unit test reports must use JUnit XML format with specific requirements to ensure proper parsing and display.

Your test report files must:

  • Use JUnit XML format with .xml file extension.
  • Be smaller than 30 MB per individual file.
  • Have a total size under 100 MB for all JUnit files in a job.

If you have duplicate test names, only the first test is used and others with the same name are ignored.

For test case limits, see Maximum test cases per unit test report.

Test result types

Test results are compared between the merge request’s source and target branches to show what changed:

  • Newly failed tests: Tests that passed on the target branch but failed on your branch.
  • Newly encountered errors: Tests that passed on the target branch but had errors on your branch.
  • Existing failures: Tests that failed on both branches.
  • Resolved failures: Tests that failed on the target branch but passed on your branch.

If branches cannot be compared, for example when there is no target branch data yet, only the failed tests from your branch are shown.

For tests that failed in the default branch in the last 14 days, you see a message like Failed {n} time(s) in {default_branch} in the last 14 days. This count includes failed tests from completed pipelines, but not blocked pipelines. Support for blocked pipelines is proposed in issue 431265.

Configure unit test reports

Configure unit test reports to display test results in merge requests and pipelines.

To configure unit test reports:

  1. Configure your test job to output JUnit XML format test reports. For configuration details, review your testing framework’s documentation.
  2. In your .gitlab-ci.yml file, add artifacts:reports:junit to your test job.
  3. Specify the path to your XML test report files.
  4. Optional. To make report files browsable, include them with artifacts:paths.
  5. Optional. To upload reports even when jobs fail, use artifacts:when:always.

Example configuration for Ruby with RSpec:

ruby:
  stage: test
  script:
    - bundle install
    - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml
  artifacts:
    when: always
    paths:
      - rspec.xml
    reports:
      junit: rspec.xml

You can view test results:

  • In the Tests tab of pipeline details after your test job completes.
  • In the Test summary panel of merge requests after your pipeline completes.

View test results in merge requests

View detailed information about test failures in merge requests.

The Test summary panel shows an overview of your test results, including how many tests failed and passed.

Expanded Test summary panel that shows one failed test with the View details link

To view test failure details:

  1. In a merge request, go to the Test summary panel.
  2. To expand the Test summary panel, select Show details ( chevron-lg-down ).
  3. Select View details next to a failed test.

The dialog displays the test name, file path, execution time, screenshot attachment (if configured), and error output.

To view all test results:

  • From the Test summary panel, select Full report to go to the Tests tab in the pipeline details.

Copy failed test names

Copy test names to rerun them locally for debugging.

Prerequisites:

  • Your JUnit report must include <file> attributes for failed tests.

To copy all failed test names:

  • From the Test summary panel, select Copy failed tests ( copy-to-clipboard ).

The failed tests are copied as a space-separated string.

To copy a single failed test name:

  1. To expand the Test summary panel, select Show details ( chevron-lg-down ).
  2. Select View details next to the test you want to copy.
  3. In the dialog, select Copy test name to rerun locally ( copy-to-clipboard ).

The test name is copied to your clipboard.

View test results in pipelines

View all test suites and cases in pipeline details.

To view pipeline test results:

  1. Go to your pipeline details page.
  2. Select the Tests tab.
  3. Select any test suite to see individual test cases.

Pipeline test results

You can also retrieve test reports with the Pipelines API.

Add screenshots to test reports

Add screenshots to test reports to help debug test failures.

To add screenshots to test reports:

  1. In your JUnit XML file, add attachment tags with screenshot paths relative to $CI_PROJECT_DIR:

    <testcase time="1.00" name="Test">
  <system-out>[[ATTACHMENT|/path/to/some/file]]</system-out>
</testcase>

  2. In your .gitlab-ci.yml file, configure your job to upload screenshots as artifacts:

    • Specify the path to your screenshot files.
    • Optional. Use artifacts:when: always to upload screenshots when tests fail.

    For example:

    ruby:
  stage: test
  script:
    - bundle install
    - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml
    - # Your test framework should save screenshots to a directory
  artifacts:
    when: always
    paths:
      - rspec.xml
      - screenshots/
    reports:
      junit: rspec.xml

  3. Run your pipeline.

You can access the screenshot link in the test details dialog when you select View details for a failed test in the Test summary panel.

A failed unit test report with test details and screenshot attachment

Troubleshooting

Test report appears empty

You might see an empty Test summary panel in merge requests.

This issue occurs when:

  • Report artifacts have expired.
  • JUnit files exceed size limits.

To resolve this issue, set a longer expire_in value for the report artifact, or run a new pipeline to generate a new report.

If JUnit files exceed size limits, ensure:

  • Individual JUnit files are less than 30 MB.
  • The total size of all JUnit files for the job is less than 100 MB.

Support for custom limits is proposed in epic 16374.

Test results are missing

You might see fewer test results than expected in your reports.

This can happen when you have duplicate test names in your JUnit XML file. Only the first test for each name is used and duplicates are ignored.

To resolve this issue, ensure all test names and classes are unique.

No test reports appear in merge requests

You might not see the Test summary panel at all in merge requests.

This issue can happen when the target branch has no test data for comparison.

To resolve this issue, run a pipeline on your target branch to generate baseline test data.

JUnit XML parsing errors

You might see parsing error indicators next to job names in your pipeline.

This can happen when JUnit XML files contain formatting errors or invalid elements.

To resolve this issue:

  • Verify your JUnit XML files follow the standard format.
  • Check that all XML elements are properly closed.
  • Ensure attribute names and values are correctly formatted.

For grouped jobs, only the first parsing error from the group is displayed.