unit-coverage

The unit suite clears a 100% floor — whole-tree on every run, and over the changed lines on every pull request. This page is the complete record of the check: why the floor is strict, what each language measures, when the two jobs run, and every key that tunes it.

Why this check exists

A test can exist without running the code — coverage is the unit ladder's second rung: does the test run it? And the floor is 100 rather than a comfortable 85 because a lower floor hides a permanent, unexamined gap: at fail_under = 85, fifteen percent of the code is uncovered and nobody has said which fifteen or why — the number stays green while the uncovered region drifts to wherever tests are hardest to write. The standard inverts this: the floor is 100% of what you didn't explicitly exempt, so every uncovered line is either covered or named with a reason.

A covered line proves execution, nothing more — a test that calls the function and asserts nothing covers every line it touches. mutation is the rung above.

What it enforces

The floor applies to the unit suite only — test files are excluded from the denominator, and exempted files/lines are lifted from it. The exact keys and defaults are in the configuration reference.

• Python — the suite runs under coverage.py with branch coverage on; the combined line + branch total meets fail_under. A source with no branching constructs measures zero branches, which is vacuously full branch coverage — the total reduces to the line percent. pytest collects only the scanned path, with the standard suite tiers under tests/ ignored, so the integration tier stays out of the unit lane the same way it stays out for TypeScript and Rust.
• TypeScript — the suite runs under vitest v8 coverage; four independent metrics (lines, branches, functions, statements) each meet their floor, because line coverage can read 100% while a branch lags.
• Rust — the suite runs under cargo llvm-cov --lib --bins, so the floor measures the same unit-only slice the other languages measure (the integration tier under tests/ stays out of the number) across both the library and the binary targets — a binary's colocated tests are units too. The default floors lines only; three finer metrics are opt-in: regions is a Rust-only sub-line metric with a harsher bar and no cross-language analog, functions mirrors TypeScript's, and branch instruments on a nightly toolchain, which the crate pins in its own rust-toolchain.toml (with llvm-tools-preview) — the coverage run reads that pin, in CI and locally alike (the config reference has the exact keys). Keeping them opt-in keeps Rust's default floor line-shaped like Python's — the parity call, with the asymmetry named here.

Where the tool runs

Each coverage run anchors where the consumer's own test run anchors, so the check measures the suite under the same configuration your own runs use:

• TypeScript — vitest runs at the scanned path and resolves its configuration with its own upward search, so the package-root vitest.config.* that governs your own vitest run governs the check's run the same way: environment, setup files (resolved beside the config file), aliases, and plugins all apply. The check owns the measurement itself: its flags set the coverage scope (the scanned path's sources are the denominator, and the package's suite tiers under tests/ stay out of the run), its floors come from your testing-conventions.toml config, and the run clears the config file's own global coverage thresholds — the check's floors decide, and your config file is left untouched (a thresholds.autoUpdate never rewrites it during a check run).
• Python — coverage.py runs at the scanned path, and pytest resolves its rootdir and configuration with its own upward search — so a package-root [tool.pytest.ini_options] / pytest.ini and the conftest.py files below it apply to the check's run exactly as to your own pytest run. The measurement itself is owned by the check — the scanned path's sources are the denominator (--source), branch coverage on, test files and exempted paths omitted, floors from your testing-conventions.toml config — so a .coveragerc / [tool.coverage] table is deliberately not consulted: the check holds the same keys it overrides in a vitest config, and the denominator is the scanned path's sources, addressing the same paths every other check uses. Scoping to the scanned path keeps an editable path dependency's source tree out of the number — a normal install lands in site-packages and is ignored either way, but an editable install resolves through a .pth to a tree that is not under site-packages, which coverage.py's default would otherwise pick up. (# pragma: no cover is coverage.py's built-in default and applies without configuration.) pytest's collection is scoped the same way: a tests/ directory directly beneath the scanned path is ignored, so a package whose scanned path is its package root never collects its own tests/integration/ or tests/e2e/ into the unit run.
• Rust — cargo llvm-cov --lib --bins anchors at the crate root by construction: cargo resolves the manifest upward from the scanned path, and .cargo/config.toml / rust-toolchain.toml discovery is cargo's and rustup's own, exactly as in your own cargo test.

An item the test build never compiles

In Rust, an item a #[cfg(not(test))] gate keeps out of the test build is not a coverage subject, whole-tree or changed-line. The unit tier runs cargo llvm-cov --lib --bins, which sets cfg(test), so no test can execute the item; the --bins half nevertheless links the library a second time as a plain dependency of the binary target's test harness, where cfg(test) is unset, and the gated item is compiled and instrumented there. Whether its counters reach the report depends on how the linker partitioned that build — CARGO_INCREMENTAL=0 alone flips it — so the check drops the item's regions, lines, functions, and branches from the ratios instead.

The exclusion is item-level and covers only a gate a test build genuinely cannot satisfy: #[cfg(not(test))] and #[cfg(all(not(test), unix))] qualify, #[cfg(any(not(test), unix))] still compiles under cargo test and stays a subject. This is what makes the binary entry point colocated-test documents coverage-clean, the same way mutation drops the mutants inside it.

Which view the Rust line ratio reads

The same --lib --bins run compiles the library twice, so llvm-cov holds two instantiation groups for every file in it. A --json export's totals sum each group's own line tally, which counts a line both groups map twice — once covered and once not, when only one group ran it. The floor reads the DA: records of an lcov export instead: llvm-cov writes those through the merged line view that llvm-cov show, --text and --show-missing-lines all read, where a line maps once however many groups carry it.

Both exports come from one run — the check re-reads the profile rather than running the suite twice — so a failing line ratio always names lines those views can show. Regions, functions and branches still come from the --json totals, where the same summing is what the gated-item subtraction above is written against.

The changed-line job

On pull requests, the same configured floor is also measured over only the lines the <base>...HEAD diff added or modified. The thresholds stay the single source of truth; the diff-scoped job only changes what they're measured over — a one-line change below the floor fails however small the diff is, an added file's new lines are subjects, and a change touching no measured line passes vacuously.

When it runs

Variant	Runs	As
Whole-tree	always	its own job per language
Changed-line	pull requests only, over <base>...HEAD	its own job per language

Both jobs install, provision, and build at the derived package root: Python is provisioned by uv (uv sync for an installable package, else a fresh uv venv, with the suite toolchain installed into that same .venv); TypeScript installs with the package's own lockfile (pnpm install --frozen-lockfile or npm ci) and runs vitest v8 coverage; Rust runs cargo llvm-cov --lib --bins with no install step of its own. A package whose suite imports a compiled module builds it first via build_command. The gates input names it unit-coverage; the changed-line variant rides with it.

Configuration

A [<language>].coverage table is a partial override — set only the fields you want to move, the rest keep their default, and a typo'd key is rejected:

Language	Keys	Default
Python	branch, fail_under	branch = true, fail_under = 100. The suite always runs under coverage.py's branch instrumentation, so the whole-tree floor is its combined line + branch percent; a source with no branching constructs measures zero branches and is vacuously at full branch coverage. branch decides whether the diff-scoped and line-exempt ratios fold branch arcs in alongside lines.
TypeScript	lines, branches, functions, statements	All four at 100, each enforced independently.
Rust	lines, regions, functions, branch	lines = 100; the rest are opt-in floors. A branch floor adds --branch, which runs on the nightly toolchain the crate pins in its own rust-toolchain.toml (with llvm-tools-preview).

Related keys and surfaces:

• [rust] features — cargo features the coverage run enables, so #[cfg(feature = ...)] code is compiled and measured.
• build_command — a pre-suite build the manifest can't express (a maturin/PyO3 extension).
• The floor is also published as a shared test config your own runner extends, so a local run is held to the same floor CI enforces.

A coverage exemption is line-scoped, never whole-file: the entry carries a lines list naming the exact failing lines, with a required reason, and a determinism guard rejects a listed line that isn't actually failing — see the exemption schema.

Learn more

• Explanation — Coverage: why 100, in full.
• Respond to a red check: lowering a floor, step by step.