How to Fail CI Under a pytest Coverage Threshold

pytest --cov-fail-under=N makes the run fail when total coverage is below N percent.

Pass --cov-fail-under=<N> on the command line or set fail_under in the coverage config. Either way pytest returns a non-zero exit code when coverage is short.

Steps

• Add --cov-fail-under=<N> to the pytest command, or set fail_under in config.
• Keep --cov=<package> so the percentage reflects your code.
• A shortfall exits non-zero and fails the CI job.

Terminal

pytest --cov=myapp --cov-report=term-missing --cov-fail-under=85

pyproject.toml

[tool.coverage.report]
fail_under = 85
show_missing = true

Gotchas

• The command-line --cov-fail-under overrides the config fail_under when both are present.
• The threshold is checked against the combined total, so parallel runs must be merged before the check.

Related guides