Getting Started

This section describes what you need to know to use effectively OpenCppCoverage.

More information are also available:

If you have any questions or issues, you should have a look at the FAQ.

HTML report content

OpenCppCoverage creates code coverage report in HTML format.

Modules

The code coverage is hierarchical:

  • Modules: executable and shared libraries
  • Source files by module
  • Lines by source file

You can see the code coverage in percent and also the total of covered and uncovered lines count.

Requirements

Program database

OpenCppCoverage use program database file (.pdb) to know which source lines contain code and for html report.

Basically, you just need your executable, the source code and the program database files. If you can debug your code, everything should be fine.

Note that a program database file contains the original source paths. If you move your sources location, you need to regenerate the program database files by rebuilding your solution (like for debugging your code).

Release versus Debug

In release build, your code can be optimized aggressively. For example, you can have strange behaviors when debugging a release build. Same kinds of issues occur with code coverage.

Useful command line flags

OpenCppCoverage has several flags. You can find a complete description  here.

Select files for coverage: --sources

By default, OpenCppCoverage performs code coverage for every file accessible through program database files that means:

  • Your source code
  • Visual studio internal files
  • External libraries

You probably want to perform the code coverage only for your sources. OpenCppCoverage need a way to distinct your source files and headers from external code. You can use --sources flags like in the following example:

OpenCppCoverage --sources C:\Dev\MyProject -- YourProgram.exe

The code coverage will be performed only for sources whose path contains C:\Dev\MyProject.

This flag is also useful if you want to perform code coverage only for a subset of your source files. For example, it allows you to run code coverage only for a new development or for code in static library.

Merging coverage: --input_coverage / --export_type:binary

Sometimes, it can be useful to have a global overview of the coverage for several test programs. However OpenCppCoverage allow you to run a single program at a time.

You can use --export_type:binary to save a code coverage and merge it with other coverage reports.

OpenCppCoverage --sources=MySources --export_type=binary:Test1.cov -- Test1.exe
OpenCppCoverage --sources=MySources --export_type=binary:Test2.cov -- Test2.exe
OpenCppCoverage.exe --sources=MySources --input_coverage=Test1.cov --input_coverage=Test2.cov  -- Test3.exe

The first two lines create code coverage report for Test1.exe (Test1.cov) and Test2.exe (Test2.cov). The last line loads the coverage files Test1.cov and Test2.cov, runs Test3.exe and produces a single report. This report contains the code coverage for Test1.exe, Test2.exe and Test3.exe.

Faster startup: --modules

If you have a lot of external libraries with program database files and source code, the startup can be quite slow.

In the same way as --sources allow you to select the source files for the coverage, --modules does the same job for the executable and the shared libraries.

OpenCppCoverage --modules C:\Dev\MyProject -- YourProgram.exe

The code coverage will be performed only for modules whose path contains C:\Dev\MyProject.

for each module, OpenCppCoverage iterates over all source files and checks if the file is selected or not. When using --modules, you avoid this file iteration.

Jenkins: --export_type=cobertura

OpenCppCoverage supports Jenkins. Click here for more information.

Last edited Mar 5 at 4:05 PM by OpenCppCoverage, version 18