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
HTML report content
OpenCppCoverage creates code coverage report in HTML format.
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.
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
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.
OpenCppCoverage supports Jenkins.
Click here for more information.