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
  1. Build your tests with debug symbols (PDBs)
  2. Run tests under covdbg to produce .covdb
  3. Export to LCOV or Cobertura XML (or GCOV) for downstream tooling
  4. 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

  1. Run on every PR: get coverage feedback before merge
  2. Use consistent filters: keep .covdbg.yaml in version control
  3. Store artifacts: save .covdb and exports for debugging
  4. Set a coverage threshold: enforce a minimum in your coverage service or quality gate, such as Codecov

Platform-Specific Guides

See Also