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
• Building OpenCppCoverage
• Writing an export plugin

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

The first step is to download the latest version of OpenCppCoverage and install it.

Let's continue by creating a new C++ console application.

• Open the New Project window from Visual Studio menu File/New/Project....
• Select Installed/Visual C++/Windows Desktop/Windows Console Application, name it ConsoleApplication1 and create the project.
• Build the project ConsoleApplication1

In the root folder containing ConsoleApplication1.sln, open a new command line (cmd.exe or Windows PowerShell) and execute the following command: OpenCppCoverage -- .\Debug\ConsoleApplication1.exe

The report is generated in CoverageReport-YEAR-MONTH-DAY-TIME folder.

Open CoverageReport-YEAR-MONTH-DAY-TIME\index.html. You should see something similar to the screen below.

Then, click on the link C:\Dev\ConsoleApplication1\Debug\ConsoleApplication1.exe and you should see the coverage by files.

As you can see, there are many files. Even for a simple Hello World application, your program links with several libraries and this why you have several files listed. OpenCppCoverage needs a little help to display only what you want. This is where the command line option --sources helps.

OpenCppCoverage --sources ConsoleApplication1 -- .\Debug\ConsoleApplication1.exe

The previous command line computes coverage only for the source files whose path contains "ConsoleApplication1". In your case, only consoleapplication1.cpp should match.

Note: The last -- signifies the end of the options. See here for more information.

Now, your coverage report should contains only one module (ConsoleApplication1.exe) and one source file (consoleapplication1.cpp). The coverage of consoleapplication1.cpp should look like this:

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).

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

For example, consider the following code:

int bar(int n)
{
	int sum = 0;
	for (int i = 0; i < n; ++i)
		sum += i;
	return sum;
}
int foo(int v)
{
	if (v > 0)
		return bar(v);
	return v;
}
int main()
{
	return foo(10);
}

These three functions are translated in release build into

mov eax,2Dh 
ret 		// Return 45

The generated code can be completely different compared to the original source code.
OpenCppCoverage should be used with a debug build. If you need to use a release build, you may expect some inaccuracies.

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

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.

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.

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.