Coverage Gates
Coverage gates block merges below a threshold — effective as ratchets on changed lines, misleading as global percentages that invite gaming and hide untested critical paths.
Definition
A coverage gate is a CI check failing builds below a configured coverage threshold. Diff coverage — the fraction of newly changed lines that are tested — drives improvement without litigating legacy debt. Global thresholds generate perverse incentives: chasing percentage via trivial tests, testing getters to move a number, and deleting risky code instead of testing it.
Context and scope
Configured in CI on pull requests with changed-line coverage, trend enforcement against the main branch, and separate expectations per suite type — unit versus integration versus e2e.
Common misconceptions
- Coverage percentage measures test quality — it measures execution reach only; assertion strength needs mutation or review
- Raising the global threshold fixes the backlog — it forces gaming; diff coverage fixes the margin while leaving history alone
- Coverage tools report the truth — exclusions, dead code marking, and generated code handling silently shape the number
Anti-patterns
- Setting a global 80 percent gate and receiving ten thousand assertion-free tests that execute everything
- Excluding whole directories from measurement to satisfy the gate and calling the codebase covered
- Blocking PRs on coverage dips in generated or vendored code and burning goodwill on noise
Related concepts
Authoritative source
What it is
Coverage turns testing discipline into an enforceable number. The gate says: code you change must be exercised. Used as a ratchet it compounds; used as a score it corrupts.
How it works
Instrumentation tracks executed lines per test run. Diff coverage intersects that map with the patch — the check asks whether this PR adds untested behavior. Trend mode fails any decrease relative to main, tolerating imperfect history while guaranteeing non-regression.
When to gate
On changed lines for applications, on public API surface for libraries. Pair the gate with review guidance: the number flags omissions; humans judge whether the tests say anything.
Pitfalls
Percentage worship produces assertion-free execution tests — coverage identical to real suites, value near zero. Generated code and vendored trees need exclusion hygiene or they drown the signal. Coverage says nothing about branches not taken by any test — branch coverage narrows but never closes that gap.