pytest-cov: Measuring & Reporting Coverage

pytest-cov is a pytest plugin built on top of coverage.py, the underlying engine that instruments and tracks which lines of code actually execute during a test run. It integrates coverage measurement directly into pytest's own CLI.

Running with Coverage

pip install pytest-cov

# Measure coverage for the mypackage package during the test run
pytest --cov=mypackage

# Show the specific uncovered line numbers in the terminal output
pytest --cov=mypackage --cov-report=term-missing

# Generate a browsable HTML report at htmlcov/index.html --
# green-highlighted covered lines, red/pink uncovered ones
pytest --cov=mypackage --cov-report=html

# Machine-readable XML, commonly consumed by CI coverage services
# like Codecov or Coveralls
pytest --cov=mypackage --cov-report=xml

Enforcing a Coverage Floor in CI

# Exits non-zero if total coverage falls below 80% -- this is what
# actually lets a CI pipeline block a merge on insufficient coverage
pytest --cov=mypackage --cov-fail-under=80

A pragmatic threshold (often 70-90%, project-dependent) catches modules with essentially no tests without demanding coverage of every trivial line. Chasing 100% can encourage shallow tests written just to hit lines rather than to verify real behavior.

Line Coverage Is a Floor, Not a Guarantee

def divide(a, b):
    return a / b

# This test EXECUTES divide(), contributing to 100% line coverage on
# it, but asserts nothing about the actual result -- coverage answers
# "did this line run?", not "was it verified to behave correctly?"
def test_divide():
    divide(10, 2)  # no assertion at all