Getting Started

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

More information are also available:

• Command line flags
• Visual Studio Extension
• Jenkins support
• Roadmap

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.

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.

OpenCppCoverage works only in debug (not optimized) build.

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. HoweverOpenCppCoverage 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) andTest2.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 forTest1.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.

FAQ

How to specify argument for my program?

if you run the following command you will have a parsing error: unrecognised option '--arg1'.

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

The parser need a way to know that --arg1 is a flag of YourProgram.exe and not forOpenCppCoverage.exe. You need to add ‘--‘ before your executable name in the same way as many Unix command does.

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

I cannot see my module in the code coverage report.

When running OpenCppCoverage, it starts by displaying information about why a module is selected or not. For example you can have:

[info] Module: C:\Dev\MyProject\YourProgram.exe is selected because it matches selected pattern: MyProject

Or

[info] Module: C:\Dev\MyProject\YourProgram.exe is not selected because it matches excluded pattern: MyProject

If your module is not selected, check the value of --modules and --excluded_modules.

I cannot see my file in the code coverage report.

You can use --verbose flag as command line to show why a file is selected or not:

[debug] Filename: C:\Dev\MyProject\main.cpp is skipped because it matches no selected patterns

The output is also written in file LastCoverageResults.log. It contains also information about the location of program data files used.

You can also check that your program database files are up-to-date by adding a breakpoint inside the file and try to debug.

Is Windows XP supported?

Windows XP is currently not supported.

Why there is an uncovered line at the end of my class declaration with Visual Studio 2013?

You can have an uncovered line at the end of the class like in following code:

You will have this behavior if your class have all the following requirements:

• At least one default method
• Is exported with __declspec(dllexport)
• Has only basic types (int, bool) but no std::string, std::vector or any user class.

Even if you call the methods marked with = default, this line will be remained uncovered.

This is not a bug because there is code generated for the method marked with= default that is never called.

To avoid this problem you can:

• Remove = default from the method declaration (in the header)
• Implement your method with = default in your source file (in .cpp)

For example, for a default copy constructor of the class MyClass, you should define in your source file (.cpp)

MyClass::MyClass(const MyClass&) = default;

Coverage and throw

Consider the following output of OpenCppCoverage:

Each line is executed, but line 14 is marked as uncovered.

As foo has a destructor, the compiler adds a call to the destructor at the end of the scope. Of course, it will never be called because of the exception.

If you have an object with a destructor in the same scope as a throw, you will have this issue. You also have this case, if you declare a local variable of typestd::exception before throwing.

You can add a new scope around your variable like in the following code:

Network path special considerations

Consider a Visual Studio project shared at \\YOUR-COMPUTER\Shared\ConsoleApplication andZ:\ConsoleApplication (Z: is a network drive that maps \\YOUR-COMPUTER\Shared).

The following methods for running the program are equivalent:

Method 1: OpenCppCoverage --sources ConsoleApplication -- Z:\ConsoleApplication\Debug\ConsoleApplication.exe
Method 2: OpenCppCoverage --sources ConsoleApplication -- \\YOUR-COMPUTER\Shared\ConsoleApplication\Debug\ConsoleApplication.exe

For module filtering (--modules and --excluded_modules), you need to always use the network style that is\\YOUR-COMPUTER\Shared\ConsoleApplication.

For source filtering (--sources and --excluded_sources), thing are little more complex because it depends on how the project was compiled and not how the program is run:

• If you open Visual Studio solution using Z:\ConsoleApplication\ConsoleApplication.sln and then compile, you should useZ:\ConsoleApplication style for filtering.
• If you open instead \\YOUR-COMPUTER\Shared\ConsoleApplication\ConsoleApplication.sln and then compile, you should use\\YOUR-COMPUTER\Shared\ConsoleApplication style for filtering.

It is highly recommended to run OpenCppCoverage in verbose mode when settings filters.