pytest-cov "--cov-fail-under" Threshold Not Met in CI

--cov-fail-under=M makes pytest exit non-zero when total coverage drops below M. Either coverage genuinely fell, or the measurement under-counted (wrong --cov target, parallel data not combined) so the reported total is artificially low.

What this error means

Tests pass but the job fails at the end with Coverage failure: total of N is less than fail-under M. The exit code is non-zero purely because of the coverage gate, not a test failure.

pytest output

Required test coverage of 90% not reached. Total coverage: 84.21%
FAIL Required test coverage of 90% not reached.

Common causes

Coverage genuinely dropped below the gate

New untested code, or removed tests, pushed the total under the threshold. This is the gate working as intended.

Measurement missed source

A wrong --cov=<pkg> target, code imported before coverage started, or parallel .coverage.* files never combined make the total lower than reality.

How to fix it

Measure the right package and combine data

Point --cov at the installed package and combine parallel data before reporting.

Terminal

pytest --cov=myapp --cov-report=term-missing
# if using parallel/xdist:
coverage combine && coverage report --fail-under=90

Raise coverage or adjust the gate deliberately

Use --cov-report=term-missing to see which lines are uncovered.
Add tests for the newly uncovered code paths.
Only lower --cov-fail-under as a conscious, reviewed decision.

How to prevent it

Measure the installed package and combine parallel coverage data.
Track coverage in PRs so drops are visible before merge.
Treat the threshold as a deliberate, reviewed number.