/gcovr

generate code coverage reports with gcc/gcov

Primary LanguagePythonOtherNOASSERTION

gcovr

generate GCC code coverage reports

website • documentation • bugtracker • GitHub

GitHub Actions build status install from PyPI Codecov status Gitter chat

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:

  • default or --txt<gcovr --txt>: compact human-readable summaries
  • --html<gcovr --html>: HTML summaries
  • --html-details<gcovr --html-details>: HTML report with annotated source files
  • -x/--xml<gcovr --xml>: machine readable XML reports in Cobertura format
  • --sonarqube<gcovr --sonarqube>: machine readable XML reports in Sonarqube format
  • --json<gcovr --json>: JSON report with source files structure and coverage
  • --json-summary<gcovr --json-summary>: JSON summary coverage report
  • --csv<gcovr --csv>: CSV report summarizing the coverage of each file
  • --coveralls<gcovr --coveralls>: machine readable JSON reports in Coveralls 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:

image

Example HTML details:

image

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

You can also generate detailed HTML reports:

gcovr -r . --html --html-details -o coverage.html

Gcovr will create one HTML report per source file 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 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/master/CONTRIBUTING.rst

License

Copyright 2013-2021 the gcovr authors

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

Gcovr is available 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.