Development Status
- 5 - Production/Stable
Environment
- Console
Intended Audience
- Developers
- Science/Research
License
- OSI Approved :: BSD License
Natural Language
- English
Operating System
- MacOS :: MacOS X
- Microsoft :: Windows
- POSIX
- Unix
Programming Language
- Python
- Python :: 3
- Python :: 3.10
- Python :: 3.11
- Python :: 3.12
- Python :: 3.13
- Python :: 3.14
Topic
- Software Development
- Software Development :: Quality Assurance
- Software Development :: Testing
- Utilities
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 |
compact human-readable summaries |
|
--html |
overview of all files |
|
--html-details |
annotated source files |
|
--html-template-dir |
use custom set of Jinja2 templates |
|
--csv |
CSV report summarizing the coverage of each file |
|
--json |
JSON report with source file structure and coverage |
|
--json-summary |
JSON summary coverage report |
|
--markdown |
Markdown coverage report |
|
--markdown-summary |
Markdown summary coverage report |
|
--clover |
machine readable XML reports in Clover format |
|
--cobertura |
machine readable XML reports in Cobertura format |
|
--coveralls |
machine readable JSON report in Coveralls format |
|
--jacoco |
machine readable XML reports in JaCoCo format |
|
--lcov |
machine readable report in LCOV info format |
|
--sonarqube |
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 gcovrInstall development version from GitHub (needs at least version 21.3 of pip):
pip install git+https://github.com/gcovr/gcovr.gitQuickstart
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://gcovr.com/en/latest/contributing.html
License
This software is distributed under the 3-clause BSD License. See https://gcovr.com/en/latest/license.html#license-terms for details. See https://gcovr.com/en/latest/license.html#acknowledgements for the full list of contributors.
