gcovr

generate GCC code coverage reports

website and documentation • bugtracker • GitHub

Gcovr provides a utility for managing the use of the GNU gcov utility and generating summarized code coverage results. This command is inspired by the Python coverage.py package, which provides a similar utility for Python.

The gcovr command can produce different kinds of coverage reports:

CLI Option	User Guide	Description
default, --txt	Text Output	compact human-readable summaries
--html	HTML Output	overview of all files
--html-details	HTML Output	annotated source files
--html-template-dir	HTML Output	use custom set of Jinja2 templates
--csv	CSV Output	CSV report summarizing the coverage of each file
--json	JSON Output	JSON report with source file structure and coverage
--json-summary	JSON Output	JSON summary coverage report
--clover	Clover XML Output	machine readable XML reports in Clover format
--cobertura	Cobertura XML Output	machine readable XML reports in Cobertura format
--coveralls	Coveralls JSON Output	machine readable JSON report in Coveralls format
--jacoco	JaCoCo XML Output	machine readable XML reports in JaCoCo format
--lcov	LCOV info Output	machine readable report in LCOV info format
--sonarqube	SonarQube XML Output	machine readable XML reports in SonarQube format

Thus, gcovr can be viewed as a command-line alternative to the lcov utility, which runs gcov and generates an HTML-formatted report. The development of gcovr was motivated by the need for text summaries and XML reports.

Example HTML summary:

Example HTML details:

Installation

Gcovr is available as a Python package that can be installed via pip.

Install newest stable gcovr release from PyPI:

pip install gcovr

Install development version from GitHub:

pip install git+https://github.com/gcovr/gcovr.git

Quickstart

GCC can instrument the executables to emit coverage data. You need to recompile your code with the following flags:

--coverage -g -O0

Next, run your test suite. This will generate raw coverage files.

Finally, invoke gcovr. This will print a tabular report on the console.

gcovr

You can also generate detailed or nested HTML reports:

gcovr --html-details coverage.html
gcovr --html-nested coverage.html

Gcovr will create one HTML report per source file and for --html-nested also per directory next to the coverage.html summary.

You should run gcovr from the build directory. The -r option should point to the root of your project. This only matters if you have a separate build directory. For example:

cd build; gcovr -r ..

For complete documentation, read the manual.

Contributing

If you want to report a bug or contribute to gcovr development, please read our contributing guidelines first: https://github.com/gcovr/gcovr/blob/main/CONTRIBUTING.rst

License

Copyright (c) 2013-2024 the gcovr authors Copyright (c) 2013 Sandia Corporation. Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains certain rights in this software.

This software is distributed under the 3-clause BSD License. See LICENSE.txt for full details. See AUTHORS.txt for the full list of contributors.

Gcovr development moved to this repository in September, 2013 from Sandia National Laboratories.