pytest-cov "Required test coverage of X% not reached" in CI

By Daniel Zoghalchali·Latchkey

pytest-cov measured total coverage below the --cov-fail-under percentage, so coverage prints "FAIL Required test coverage of X% not reached" and pytest exits with a non-zero code, failing the job.

What this error means

After the test run, the report shows "FAIL Required test coverage of 80% not reached. Total coverage: 72.34%" and pytest returns a failing exit code.

FAIL Required test coverage of 80% not reached. Total coverage: 72.34%

Common causes

Coverage genuinely fell below the gate

New code without tests pulled the total under the --cov-fail-under value passed on the command line or in config.

The measured scope is wider than the tests cover

A broad --cov target (the whole package) includes modules the tests do not exercise, lowering the total.

How to fix it

Add tests, or set the gate to a realistic value

1. Open the term-missing report or HTML to find uncovered lines.
2. Add tests for the gaps.
3. If 80% is not yet realistic, set --cov-fail-under to the current honest baseline and raise it over time.

pytest --cov=src --cov-report=term-missing --cov-fail-under=80

Scope coverage to what tests target

Measure the package under test, and omit modules you do not intend to cover, so the total reflects real coverage.

# .coveragerc
[run]
source = src
omit = src/migrations/*, src/*/__main__.py

How to prevent it

• Run pytest with --cov-fail-under locally before pushing.
• Scope --cov/source to the code you intend to test.
• Raise the threshold incrementally as coverage improves.

Frequently asked questions

Related guides

References

• GitHub Actions documentation