# 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:

```ini
# ==============================================================================
# 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

```bash
# 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](<https://coverage.readthedocs.io/>) and the [Coverage.py GitHub repository](<https://github.com/nedbat/coveragepy>).