Your First C++ Coverage Report on Windows

This guide takes you from nothing to your first C++ coverage report on Windows in about ten minutes, using the small sample in the covdbg-quick-start repository. Each step is a command you can paste into PowerShell.

Before you start

  • Windows 10 or 11, x64 or ARM64
  • Visual Studio 2022 or later with the Desktop development with C++ workload, or the Build Tools
  • CMake 3.20 or newer (Visual Studio includes it; use a Developer PowerShell)
  • Git
  • A GitHub account, for signing in

1. Install covdbg

Download the installer and run it, or on Windows on ARM the ARM64 installer. It installs covdbg for your Windows user, with no Administrator rights, and adds it to your PATH. Open a new terminal and check the version:

covdbg --version

It prints the version you installed. If you cannot run an installer, extract the portable ZIP instead and add its folder to your PATH. See the Installation Guide for both.

2. Sign in

covdbg login

covdbg prints a page to open and a code. Confirm the code there with your GitHub account, and choose the team to sign in for; covdbg login --team personal skips that choice. The sign-in is kept in the Windows Credential Manager, so you do this once per machine. covdbg whoami shows it:

Signed in as <email> for <team>.

Public repositories are free for everyone who signs in, and personal use covers one private repository at a time, which you can switch at any time. See pricing and the Licensing FAQ.

3. Get the sample and build it

git clone https://github.com/liasoft/covdbg-quick-start.git
cd covdbg-quick-start
cmake -S . -B build
cmake --build build --config Debug

The build writes test_app.exe and its test_app.pdb to build\Debug. covdbg reads the PDB to map the running code to your source lines, so an ordinary Debug build is all it needs: no instrumented build and no compiler flags. The sample is a public repository, so its runs are free.

File What it is
src/main.cpp The program to measure, with a branch the first run leaves uncovered
CMakeLists.txt Builds test_app.exe with debug information
.covdbg.yaml Which source files and functions covdbg counts
.github/workflows/ The same steps in GitHub Actions

4. Look at the configuration

The sample's .covdbg.yaml counts the files under src/ (src/**/*.cpp and src/**/*.h) and leaves out what is not your code: the Windows SDK, the MSVC toolchain and runtime sources, and functions the compiler generates. Start your own project from it and adjust the include patterns to your source folders. Every option is in the Configuration Reference.

5. Run it under covdbg

covdbg --config .covdbg.yaml --output .\build\Debug\test_app.covdb .\build\Debug\test_app.exe
covdbg: collecting coverage for C:\src\covdbg-quick-start\build\Debug\test_app.exe
Hello, World!
covdbg: test_app.exe exited with code 0
covdbg: coverage written to .\build\Debug\test_app.covdb
covdbg: 4 of 6 basic blocks hit (66.7%), analysis 49 ms, run 89 ms

The program's own output sits between covdbg's lines. covdbg says how the program exited, where it wrote the coverage database (test_app.covdb), and a summary of what ran. covdbg exits 0 once the database is written, also when the program failed; in CI, add --propagate-exit-code so a failing test run fails the step. See Exit Codes.

6. Read the coverage

Turn the database into a report you can open in a browser:

covdbg convert -i .\build\Debug\test_app.covdb -f HTML -o .\build\Debug\coverage-html
HTML coverage report: .\build\Debug\coverage-html\index.html

Open index.html to see each file with its covered and uncovered lines. src/main.cpp has two of its seven lines uncovered: the run took the Hello, World! path, and the greeting for a name never ran. Run the program again with a name, into a second database, and merge the two:

covdbg --config .covdbg.yaml `
  --output .\build\Debug\test_app-name.covdb `
  .\build\Debug\test_app.exe Ada
covdbg merge -i .\build\Debug\test_app.covdb `
  -i .\build\Debug\test_app-name.covdb `
  -o .\build\Debug\merged.covdb

merged.covdb covers all seven lines; convert it the same way to see both paths covered. Finding the paths your tests never take, and adding the test that takes them, is what coverage is for.

For other tools, export LCOV or Cobertura XML the same way, such as covdbg convert -i .\build\Debug\test_app.covdb -f LCOV -o .\build\Debug\test_app.lcov. See HTML Reports and Report Formats.

To see the coverage next to your code instead, open the folder in VS Code with the covdbg extension, or in CLion with the covdbg plugin. Both load the same .covdb.

7. Add it to CI

The sample's workflow runs these steps in GitHub Actions on windows-latest and windows-11-arm: liasoft/setup-covdbg@v1 installs covdbg, and the job measures the tests with --propagate-exit-code, so a failing run fails it, and uploads LCOV and Cobertura reports. A public repository needs no secret there, only permissions: id-token: write on the job; a private one carries a project token. See GitHub Actions and CI/CD Pipelines.

What's Next?

  • Refine filters: See Configuration Reference for advanced patterns
  • Automate in CI: Set up GitHub Actions for automated coverage
  • Merge runs: Use covdbg merge to combine coverage from multiple test runs
  • Analyze uncovered code: Use covdbg analyze to include unexecuted code in reports
  • Review in the browser: Export an HTML report to read execution counts next to the source
  • Let an AI agent help: Connect your coding agent to the MCP server, or start from the AI quick start

Quick Reference

Task Command
Run coverage covdbg --config .covdbg.yaml --output out.covdb tests.exe
Export LCOV covdbg convert -i out.covdb -f LCOV -o coverage.lcov
Export Cobertura covdbg convert -i out.covdb -f COBERTURA -o coverage.xml
Export GCOV covdbg convert -i out.covdb -f GCOV -o ./gcov/
Export HTML covdbg convert -i out.covdb -f HTML -o coverage-html
Merge databases covdbg merge -i a.covdb -i b.covdb -o merged.covdb
Analyze binary covdbg analyze -i app.exe -o symbols.covdb
Serve MCP to an AI agent covdbg mcp

See the CLI Reference for complete command documentation.