pytest --cov: Coverage Command Reference for CI

Measure and enforce test coverage as part of the run.

The pytest-cov plugin adds --cov, integrating coverage.py with pytest. CI uses it to report coverage and to fail the build when it drops below a threshold.

Common flags / usage

• --cov=PKG -- measure coverage for a package or path
• --cov-report=term-missing -- show uncovered lines in the log
• --cov-report=xml -- write coverage.xml for upload tools
• --cov-fail-under=N -- fail if total coverage is below N percent
• requires: pip install pytest-cov

Example

- run: pip install pytest pytest-cov
- run: |
    python -m pytest \
      --cov=myapp --cov-report=xml \
      --cov-fail-under=85 -q

In CI

Combining --cov with xdist (-n auto) works, but make sure subprocess code is measured (coverage concurrency settings) if you spawn processes. Emit --cov-report=xml for upload to a coverage service, and gate merges with --cov-fail-under.

Key takeaways

• pytest --cov measures coverage during the test run.
• --cov-fail-under=N turns coverage into a hard CI gate.
• Emit --cov-report=xml for coverage upload integrations.

Related guides