coverage.py

coverage.py
Name	coverage.py
Author	Ned Batchelder
Developer	Ned Batchelder
Released	2004
Latest release version	7.x
Programming language	Python
Operating system	Cross-platform
License	Apache License 2.0

coverage.py coverage.py is a Python code coverage measurement tool used to determine which lines of Python code have been executed during a test run. It measures execution across modules and packages and produces human- and machine-readable reports to help developers improve test suites and detect dead code. The project is authored and maintained by Ned Batchelder and is widely adopted in conjunction with testing frameworks and continuous integration systems across open source and enterprise projects.

Overview

coverage.py collects runtime data about executed lines in Python programs by tracing execution and mapping runtime events to source files and line numbers. It is commonly used alongside pytest, unittest, nose, tox, and continuous integration services such as Travis CI, GitHub Actions, and GitLab CI/CD. The tool supports combining data from multiple runs so coverage from isolated test environments like Docker containers, virtual environments such as virtualenv and venv, and distributed test systems like Selenium Grid can be aggregated for a single coverage picture.

Features

coverage.py provides line-by-line coverage reporting, branch coverage, context-aware reporting, and data file combination. It supports measuring coverage for Python implementations including CPython, PyPy, and partial support for Stackless Python. Features include the ability to omit files or blocks via pragmas, generate HTML reports with annotated source, produce XML reports compatible with Cobertura-style consumers, and emit JSON summaries. The tool offers plugins and hooks for test runners such as pytest and build tools like tox, plus integrations with IDEs and services such as Visual Studio Code, JetBrains PyCharm, and SonarQube.

Installation and configuration

coverage.py is distributed as a Python package installable via pip and available on the Python Package Index. Installation typically involves a command referencing PyPI packages and can be managed inside virtualenv environments or system-wide across Linux distributions like Debian and Fedora. Configuration is done via a .coveragerc file or setup.cfg/pyproject.toml entries; configuration sections control omit patterns, include patterns, branch measurement, data file locations, and reporting options. Integration with package managers and build systems such as setuptools and poetry is common in projects that require reproducible environments and pinned dependency resolution.

Usage and command-line interface

coverage.py provides a command-line interface for running programs under coverage measurement, combining data files, and generating reports. Common commands include run to execute a test command, combine to merge multiple data files, html to produce an annotated website of source files, xml to emit Cobertura-compatible output, and report to print a summary to the terminal. Typical usage patterns pair commands with pytest invocations or custom test scripts; command-line options allow specifying configuration files, data file paths, and verbosity levels. The CLI interoperates with shells on platforms such as Windows, macOS and many Linux distributions, enabling scripting inside Bash and PowerShell pipelines.

Reporting and output formats

coverage.py produces several output formats: terminal summaries, HTML annotated source, XML reports compatible with Cobertura and JaCoCo-style consumers, and JSON exports for programmatic consumption. The HTML report includes per-file line highlighting and branch markers, while the XML and JSON outputs enable integration with continuous inspection tools like SonarQube and dashboarding services. Reports can be post-processed by CI systems such as Jenkins and CircleCI to enforce coverage thresholds, trigger quality gates, or upload artifacts to storage backends like Amazon S3.

Integration with development tools

coverage.py integrates with popular testing frameworks and development environments. Plugins and adapters exist for pytest, nose2, and tox, enabling seamless measurement during test runs. IDE integrations include extensions for Visual Studio Code and native support in JetBrains PyCharm for showing coverage overlays within editor views. Continuous integration and code review workflows leverage coverage output in Jenkins, Travis CI, GitHub Actions, and GitLab CI/CD to fail builds based on coverage policies or annotate pull requests using services like Codecov and Coveralls. Coverage data is also consumed by static analysis tools and dashboard systems maintained by organizations such as Mozilla and OpenStack in large-scale projects.

Implementation and architecture

coverage.py implements execution tracing using Python’s sys.settrace and native tracing hooks where available, mapping trace events to source line numbers and file names as recorded in code objects. The tool maintains an internal database of executed lines and branch arcs, which it persists in a .coverage data file that can be merged across runs. The architecture separates data collection, analysis, and reporting stages to allow offline processing and multi-run combination. For performance, coverage.py employs C extensions and optimizations selectively when running on interpreters like CPython, and adaptively disables expensive features unless configured to measure branches or contexts.

History and versioning

coverage.py was first released in the early 2000s by Ned Batchelder and has evolved through many releases to support new Python language features and packaging standards. Key milestones include adding branch coverage, HTML reporting, XML output for CI integration, and improvements for asyncio and newer PEP-driven language changes. The project follows semantic versioning practices and publishes releases on PyPI and source archives on GitHub, with contributions from an open source community spanning individual contributors and organizations that rely on its metrics for quality assurance.

Category:Python (programming language) tools