Coverage.py: Code Coverage¶

Coverage.py is the industry-standard code coverage measurement engine for Python. It monitors program execution during automated test runs, measuring which statements were executed and evaluating conditional branch decisions.

What It Does¶

Coverage.py measures both statement execution and branch coverage across Python packages. Rather than merely recording which lines were executed, branch analysis determines whether every conditional path (if, elif, else, while, and exception clauses) was evaluated for both true and false outcomes.

During test runs, Coverage.py compiles precise execution statistics into a binary .coverage database. It produces detailed terminal reports pinpointing missing line numbers (coverage report -m), machine-readable XML manifests (coverage.xml) for continuous integration reporting, and interactive HTML dashboards highlighting exact covered and missed branches in source files.

Why It's in Zenith¶

Zenith establishes a non-negotiable engineering standard: 100% mandatory statement and branch test coverage (fail_under = 100 and branch = true). In Zenith, untested code is considered uncommitted code: if even a single statement or conditional branch is missed, continuous integration pipelines fail immediately.

In AI-native workflows, 100% coverage provides a critical structural invariant. Autonomous coding agents frequently introduce partial implementations, dead branches, or untested error-handling paths. Mandating full coverage prevents untested code from reaching main, while liberating developers to execute major architectural refactors without fear of regression.

Pragmatic Coverage: Platform Margins & Custom Thresholds¶

While 100% statement and branch coverage is the default posture, real-world engineering requires pragmatic handling of operating systems and type guards:

• Built-in Exclusions: Zenith's .coveragerc pre-configures exclude_also rules for non-executable constructs:
• if TYPE_CHECKING: guards (active only during static type analysis).
• Protocol definitions and @abstractmethod signatures.
• Defensive unreachable fallbacks (assert_never, raise NotImplementedError).
• Platform-Specific Code: When code branches on specific OS platforms (e.g. if sys.platform == "win32"), use # pragma: no cover accompanied by a brief rationale comment, or combine coverage artifacts across your CI matrix runners using coverage combine.
• Customizing Thresholds: If your application domain involves heavy external sockets, C-extensions, or hardware drivers where exhaustive branch coverage yields low engineering ROI, you can pragmatically adjust fail_under = 90 directly inside .coveragerc.

Configuration in Zenith¶

Configured in .coveragerc at the project root:

# ==============================================================================
# Coverage Configuration (.coveragerc)
#
# Tool: Coverage.py / pytest-cov (https://coverage.readthedocs.io/)
# Purpose: Code coverage measurement and reporting tool for Python tests.
# Why it's in Zenith: Automatically invoked by the test runner to track branch
# coverage, exclude boilerplate lines (typing guards, repr, abstract methods), and
# enforce mandatory 100% test coverage before code can be accepted.
# ==============================================================================

[run]
branch = true
# core = sysmon
patch =
    subprocess
    _exit
source =
    src/{{ cookiecutter.package_name }}
    tests
omit =
    */__snapshots__/*
    */site-packages/*

[report]
show_missing = true
skip_covered = false
skip_empty = true
fail_under = 100
exclude_also =
    pragma: no cover
    def __repr__
    if self\.debug:
    raise AssertionError
    raise NotImplementedError
    return NotImplemented\b
    if 0:
    if __name__ == .__main__.:
    if TYPE_CHECKING:
    class .*\bProtocol\):
    @(abc\.)?abstractmethod
    @overload
    @(typing\.)?overload
    (typing\.)?assert_never
    \.\.\.

[html]
directory = htmlcov

[xml]
output = coverage.xml

Key Invocations¶

# Run test suite with mandatory 100% coverage enforcement
uv run poe test

# Display terminal coverage report with missing lines
uv run coverage report -m

# Generate interactive HTML dashboard into htmlcov/
uv run poe coverage

Upstream Documentation¶

For advanced coverage analysis, exclusion patterns, and reporting configurations, consult the Coverage.py documentation and the Coverage.py GitHub repository.