Code coverage
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Configure code coverage to track and visualize how much of your source code is covered by tests. You can:
- Track overall coverage metrics and trends using the
coverage
keyword. - Visualize line-by-line coverage using the
artifacts:reports:coverage_report
keyword.
Configure coverage reporting
Use the coverage
keyword to monitor your test coverage and enforce coverage requirements in merge requests.
With coverage reporting, you can:
- Display the overall coverage percentage in merge requests.
- Aggregate coverage from multiple test jobs.
- Add coverage check approval rules.
- Track coverage trends over time.
To configure coverage reporting:
Add the
coverage
keyword to your pipeline configuration:test-unit: script: - coverage run unit/ coverage: '/TOTAL.+ ([0-9]{1,3}%)/' test-integration: script: - coverage run integration/ coverage: '/TOTAL.+ ([0-9]{1,3}%)/'
Configure the regular expression (regex) to match your test output format. See coverage regex patterns for common patterns.
To aggregate coverage from multiple jobs, add the
coverage
keyword to each job you want to include.Optional. Add a coverage check approval rule.
Coverage regex patterns
The following sample regex patterns were designed to parse coverage output from common test coverage tools.
Test the regex patterns carefully. Tool output formats can change over time, and these patterns might no longer work as expected.
Tool | Language | Command | Regex pattern |
---|---|---|---|
pytest-cov | Python | pytest --cov | `/TOTAL.*? (100(?:.0+)?% |
Simplecov | Ruby | rspec spec | /\(\d+.\d+\%\) covered/ |
Coverage visualization
Use the artifacts:reports:coverage_report
keyword to view which specific lines of code are covered by tests in merge requests.
You can generate coverage reports in these formats:
- Cobertura: For multiple languages including Java, JavaScript, Python, and Ruby.
- JaCoCo: For Java projects only.
Coverage visualization uses artifacts reports to:
- Collect one or more coverage reports, including from wildcard paths.
- Combine the coverage information from all reports.
- Display the combined results in merge request diffs.
Coverage files are parsed in a background job, so there might be a delay between pipeline completion and the visualization appearing in the merge request.
By default, coverage visualization data expires one week after creation.
Configure coverage visualization
To configure coverage visualization:
Configure your test tool to generate a coverage report.
Add the
artifacts:reports:coverage_report
configuration to your pipeline:test: script: - run tests with coverage artifacts: reports: coverage_report: coverage_format: cobertura # or jacoco path: coverage/coverage.xml
For language-specific configuration details see:
Coverage reports from child pipelines
Coverage reports generated in child pipelines are included in the parent pipeline’s coverage report. For example:
child_test_pipeline:
trigger:
include:
- local: path/to/child_pipeline_with_coverage.yml
Add a coverage check approval rule
- Tier: Premium, Ultimate
You can require specific users or a group to approve merge requests that reduce the project’s test coverage.
Prerequisites:
To add a Coverage-Check
approval rule:
- Go to your project and select Settings > Merge requests.
- Under Merge request approvals, do one of the following:
- Next to the
Coverage-Check
approval rule, select Enable. - For manual setup, select Add approval rule, then enter the Rule name. For example:
Coverage Check
.
- Next to the
- Select a Target branch.
- Set the number of Required number of approvals.
- Select the Users or Groups to provide approval.
- Select Save changes.
View coverage results
After a pipeline runs successfully, you can view code coverage results in:
Merge request widget: See the coverage percentage and changes compared to the target branch.
Merge request diff: Review which lines are covered by tests. Available with Cobertura and JaCoCo reports.
Pipeline jobs: Monitor coverage results for individual jobs.
View coverage history
You can track the evolution of code coverage for your project or group over time.
For a project
To view the code coverage history for a project:
- On the left sidebar, select Search or go to and find your project.
- Select Analyze > Repository analytics.
- From the dropdown list, select the job you want to view historical data for.
- Optional. To view a CSV file of the data, select Download raw data (.csv).
For a group
- Tier: Premium, Ultimate
To view the code coverage history for all projects in a group:
- On the left sidebar, select Search or go to and find your group.
- Select Analyze > Repository analytics.
- Optional. To view a CSV file of the data, select Download historic test coverage data (.csv).
Display coverage badges
Share your project’s code coverage status using pipeline badges.
To add a coverage badge to your project, see test coverage report badges.
Troubleshooting
Remove color codes from code coverage
Some test coverage tools output with ANSI color codes that aren’t parsed correctly by the regular expression. This causes coverage parsing to fail.
Some coverage tools do not provide an option to disable color codes in the output. If so, pipe the output of the coverage tool through a one-line script that strips the color codes.
For example:
lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g'
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support