Report Formats
covdbg stores coverage results in a .covdb database file. You can export coverage to industry-standard formats, or to a static HTML report, using the convert command.
Coverage Database
.covdb is covdbg's native format, a SQLite-based database containing detailed coverage information.
When to Use
- Primary storage for coverage results
- Input for the
mergecommand - Input for the
convertcommand
covdbg reads only databases of its own schema version. covdbg 1.5.1 writes version 9 and refuses a .covdb written by covdbg 1.5.0 or earlier, which has to be recorded again; covdbg 1.5.0 and earlier refuse one written by covdbg 1.5.1. See Databases from Earlier Versions.
Creating a .covdb
# Run coverage and save results
covdbg --output "results.covdb" "tests.exe"
LCOV Format
LCOV is a widely-supported text-based format used by many CI/CD systems and coverage viewers.
When to Use
- Uploading to Codecov, Coveralls, or similar services
- Integration with CI/CD pipelines
- Viewing in LCOV-compatible tools
- Text-based reports that can be diffed
File Structure
LCOV files contain:
- Source file information (
SF:) - Function coverage (
FN:,FNDA:,FNF:,FNH:) - Line coverage (
DA:,LF:,LH:) - Branch coverage (if available)
From covdbg 1.5.1, functions the linker folds into one (/OPT:ICF) each have their own FN and FNDA records, by their own name in the file of their own source, and each counts in FNF and FNH. See Folded Functions.
Converting to LCOV
covdbg convert --input "results.covdb" --format LCOV --output "coverage.lcov"
Short Form
covdbg convert -i results.covdb -f LCOV -o coverage.lcov
Example Output
TN:
SF:C:\project\src\main.cpp
FN:10,main
FNDA:1,main
FNF:1
FNH:1
DA:10,1
DA:11,1
DA:12,1
DA:15,0
LF:4
LH:3
end_of_record
Cobertura Format
Cobertura XML is the format Codecov and most CI coverage dashboards read. Available from covdbg 1.5.0.
When to Use
- Uploading to Codecov, or any dashboard that expects Cobertura
- Replacing an existing Cobertura producer without touching the rest of your pipeline
- Azure DevOps, GitLab and Jenkins coverage publishing
File Structure
One XML file, conforming to Cobertura's coverage-04.dtd. Each class is a source file and each package is the module that file was compiled into, which is how OpenCppCoverage grouped its reports, so a dashboard carried over from it keeps the same structure. Function names appear as methods, and paths use forward slashes. From covdbg 1.5.1, functions the linker folds into one (/OPT:ICF) are a <method> each, by their own name in the class of their own source file, and each counts as hit when the shared code ran. See Folded Functions.
From covdbg 1.5.1, a source file compiled into several measured modules, such as a header that an executable and its DLL both include, is listed in the package of each of those modules, with the same lines and hits in each: its coverage from all of them. OpenCppCoverage lists such a file the same way. The totals on the coverage element (lines-valid, lines-covered, line-rate) still count each file once, so they are not the sum of the packages. OpenCppCoverage's totals are, and count such a file once per module, so the two headline rates can differ while every package agrees.
Filenames are relative to your source root, so a report reads src/main.cpp rather than the absolute path of whichever machine ran the tests, and the root itself is listed under sources. That is what a service like Codecov matches against your repository. Set source_root in .covdbg.yaml to control it. Without a source root there is nothing repository-relative to write, so the drive goes into sources and the rest becomes the filename. From covdbg 1.5.1, a file outside the source root, such as a runtime source a pattern includes on purpose, is named by its absolute path (D:/a/_work/1/s/src/...), as in LCOV, so it never looks like a file of your repository.
covdbg measures line and basic-block execution, not branches, so the branch counters in the file are zero rather than guessed at. A dashboard shows line coverage and a branch rate of zero.
Converting to Cobertura
covdbg convert --input "results.covdb" --format COBERTURA --output "coverage.xml"
Short Form
covdbg convert -i results.covdb -f COBERTURA -o coverage.xml
Example Output
<?xml version="1.0" encoding="UTF-8"?>
<coverage line-rate="0.7500" branch-rate="0.0" lines-covered="3" lines-valid="4"
branches-covered="0" branches-valid="0" complexity="0" version="covdbg" timestamp="1792608975">
<sources>
<source>C:/project</source>
</sources>
<packages>
<package name="C:/project/build/tests.exe" line-rate="0.7500" branch-rate="0.0" complexity="0">
<classes>
<class name="main.cpp" filename="src/main.cpp" line-rate="0.7500" branch-rate="0.0" complexity="0">
<methods>
<method name="main" signature="" line-rate="0.7500" branch-rate="0.0" complexity="0">
<lines>
<line number="10" hits="1" branch="false" />
</lines>
</method>
</methods>
<lines>
<line number="10" hits="1" branch="false" />
<line number="15" hits="0" branch="false" />
</lines>
</class>
</classes>
</package>
</packages>
</coverage>
GCOV Format
GCOV export produces one .gcov file per source file, compatible with GCC's coverage format.
When to Use
- Integration with tools expecting GCOV format
- Detailed per-file coverage reports
- When you need individual file coverage data
File Naming
For each source file foo.cpp, covdbg creates foo.cpp.gcov in the output directory.
Converting to GCOV
# Create output directory first
New-Item -ItemType Directory -Force -Path "gcov-output"
# Convert
covdbg convert --input "results.covdb" --format GCOV --output "gcov-output\"
Short Form
mkdir gcov-output
covdbg convert -i results.covdb -f GCOV -o gcov-output\
Example Output
-: 0:Source:C:\project\src\main.cpp
-: 0:Programs:1
1: 10:int main() {
1: 11: int x = 0;
1: 12: x++;
#####: 15: unreached_code();
Format:
count:line:sourcewhere count is execution times-means non-executable line#####means never executed
HTML Reports
The exporter produces a static report directory with line and function totals, file filtering, and source pages with execution counts and uncovered-line navigation:
covdbg convert --input results.covdb --format HTML --output coverage-html
Open coverage-html/index.html directly in a browser, or share the entire output directory. Reports include source text read at export time, so use the matching source revision and the same access controls as your source code.
Short Form
covdbg convert -i results.covdb -f HTML -o coverage-html
See HTML Reports for export options, source relocation, and publishing details.
Format Comparison
| Feature | .covdb |
LCOV | Cobertura | GCOV | HTML |
|---|---|---|---|---|---|
| File type | Binary (SQLite) | Text | XML | Text | Static web pages |
| Multiple files | Single file | Single file | Single file | Multiple files | Directory |
| Mergeable | Yes (merge) |
Via external tools | Via external tools | Via external tools | Merge databases before export |
| Function coverage | Yes | Yes | Yes, as methods | Limited | Yes |
| Line coverage | Yes | Yes | Yes | Yes | Yes |
| Hit counts | Yes | Yes | Yes | Yes | Yes |
| Source text | No | No | No | Yes | Yes |
| CI integration | Custom | Excellent | Excellent | Good | Publish as an artifact or static site |
Workflow Examples
CI Pipeline with Codecov
# Run tests with coverage, keeping their exit code
covdbg --propagate-exit-code --output coverage.covdb tests.exe
$testExitCode = $LASTEXITCODE
# Export to LCOV for Codecov
covdbg convert -i coverage.covdb -f LCOV -o coverage.lcov
# Upload with the Codecov CLI, which reads CODECOV_TOKEN
codecovcli upload-process --file coverage.lcov
# Fail the script when the tests failed
exit $testExitCode
A script usually ends with the exit code of its last command, so the last line keeps a failing test run from passing once the upload succeeds. See Failing the Build When Tests Fail.
Merge Multiple Test Runs
# Run different test suites, 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
See Also
- CLI Reference: command documentation
- GitHub Actions: CI integration
- HTML Reports: static browser reports