C++ Code Coverage in CI/CD Pipelines
Integrate code coverage into your continuous integration pipeline to catch regressions and track coverage trends.
Typical CI Workflow
Build Tests → Run covdbg → Export LCOV or Cobertura → Upload/Store Artifacts
- Build your tests with debug symbols (PDBs)
- Run tests under covdbg to produce
.covdb - Export to LCOV or Cobertura XML (or GCOV) for downstream tooling
- Upload to coverage services or store as artifacts
Quick Example
# 1. Run tests with coverage, keeping their exit code
covdbg --propagate-exit-code --output coverage.covdb tests.exe
$testExitCode = $LASTEXITCODE
# 2. Export to LCOV
covdbg convert -i coverage.covdb -f LCOV -o coverage.lcov
# 3. Upload with the Codecov CLI, which reads CODECOV_TOKEN
codecovcli upload-process --file coverage.lcov
# 4. Fail the script when the tests failed
exit $testExitCode
A script usually ends with the exit code of its last command, so without the last line a failing test run would pass once the upload succeeds.
Failing the Build When Tests Fail
covdbg exits 0 once it has measured the run and written the database, also when the tests failed. Pass --propagate-exit-code (or set COVDBG_PROPAGATE_EXIT_CODE=1) so covdbg exits with the exit code of the tests instead, a crash's status included, and the step fails with them. The database is still written first, so a later step can convert and upload the coverage of a failing run. covdbg's own errors exit 1. See Exit Codes. The examples on this page pass it.
Reports for Your CI System
Coverage services and CI dashboards read LCOV or Cobertura XML. covdbg writes both from the same database, so pick the one your system reads, or write both:
covdbg convert -i coverage.covdb -f LCOV -o coverage.lcov
covdbg convert -i coverage.covdb -f COBERTURA -o coverage.xml
Cobertura XML, available from covdbg 1.5.0, is what Azure DevOps, GitLab and Jenkins publish coverage from. It lists each source file in the package of the module it was compiled into, as OpenCppCoverage did, so a dashboard set up for it keeps its structure. Codecov reads either. Set source_root in .covdbg.yaml so the Cobertura export names files relative to your checkout. See Cobertura Format and Codecov.
Environment Setup
A pipeline has nobody to sign in, so it carries a project token:
$env:COVDBG_PROJECT_TOKEN = "<your-project-token>"
Store COVDBG_PROJECT_TOKEN as an encrypted secret in your CI system.
Open Source? Public repositories are free. On GitHub Actions, from covdbg 1.5.0, a public repository needs no secret at all: grant the job
id-token: write, see GitHub Actions. On other CI systems the pipeline still carries a project token, which is what names who is asking; one from your personal team will do. See Open Source for details.
Runner Architecture
Install the covdbg build for the binaries the pipeline tests: the x64 build for x64 and 32-bit x86 test binaries, and the ARM64 build, on a Windows on ARM agent, for ARM64 ones. On GitHub Actions, liasoft/setup-covdbg installs the build for the runner's architecture, so a windows-11-arm job gets the ARM64 build; see Windows on ARM runners. Elsewhere, the portable ZIPs are https://downloads.covdbg.com/covdbg-<version>-x64.zip and https://downloads.covdbg.com/covdbg-<version>-arm64.zip; each holds covdbg.exe and its agent DLLs at the top level, so extract it and add the folder to PATH. A build given a program of another architecture exits with code 1 and names the build to use. See Windows on ARM.
Clean Output
Besides your test output, covdbg prints four short lines beginning covdbg: (the program it starts, how it exited, where the database went and a one-line summary) and its errors on stderr; its log goes to a file. Use --log-level NONE to switch the log file off; the console lines stay:
covdbg --propagate-exit-code --log-level NONE --output coverage.covdb tests.exe
Merging Multiple Test Runs
If you have multiple test executables or parallel test jobs:
# Run each test suite, keeping the exit code of a failing one
$testExitCode = 0
covdbg --propagate-exit-code --output unit.covdb unit_tests.exe
if ($LASTEXITCODE -ne 0) { $testExitCode = $LASTEXITCODE }
covdbg --propagate-exit-code --output integration.covdb integration_tests.exe
if ($LASTEXITCODE -ne 0) { $testExitCode = $LASTEXITCODE }
# Merge results
covdbg merge -i unit.covdb -i integration.covdb -o merged.covdb
# Export merged coverage
covdbg convert -i merged.covdb -f LCOV -o coverage.lcov
# Fail the script when a suite failed
exit $testExitCode
Run in one script, a step usually fails only on the exit code of its last command, so the script keeps each suite's exit code and exits with it at the end; without that, failing suites would go unnoticed once the merge and conversion succeed. Or run each suite in a step of its own.
Why Automate Coverage
| Benefit | Description |
|---|---|
| Catch regressions | Fail builds when coverage drops |
| Track trends | Monitor coverage over time |
| Enforce standards | Set minimum coverage thresholds |
| Document quality | Show coverage badges in README |
Best Practices
- Run on every PR: get coverage feedback before merge
- Use consistent filters: keep
.covdbg.yamlin version control - Store artifacts: save
.covdband exports for debugging - Set a coverage threshold: enforce a minimum in your coverage service or quality gate, such as Codecov
Platform-Specific Guides
- GitHub Actions: complete workflow examples
See Also
- CLI Reference: command documentation
- Configuration: filter setup
- Report Formats: export formats