Pytest Coverage With pytest-cov: Reports, Branch Gaps and CI Gates
Pytest coverage shows which lines and branches your tests actually run. Learn the pytest-cov commands, read the missing-lines report, switch on branch coverage, generate HTML, set a fail-under gate for CI, and see why 100% line coverage can still miss a branch.
- Run pytest coverage with
pytest --cov=yourpackage --cov-report=term-missingto see the percentage and the exact lines never run. - Add
--cov-branch. In our demo, line coverage said 100% while branch coverage was 86% and pointed at the missed path. --cov-fail-under=90makes pytest exit with code 1 when coverage drops, which fails a CI build.- Coverage shows what ran, not what was checked. A test with no assertions still counts.
Your test suite is green. But does it test the error handling, the international shipping path, or that rarely used discount rule? Pytest coverage answers that question by recording which parts of your code ran during the tests. The standard tool is the pytest-cov plugin, a thin wrapper around coverage.py.
We ran every command below with pytest 9.2, pytest-cov 7.1.0 and coverage.py 7.17.3 on Python 3.13.6. The outputs are copied from those runs. If you are new to pytest, our pytest tutorial covers the basics first.
What does code coverage measure?
Coverage tools watch your program while tests run and record what executed. The two measures that matter in Python are:
- Line (statement) coverage: the share of executable lines that ran at least once.
- Branch coverage: the share of possible paths through each decision, such as both the true and false outcomes of an
if, that were taken.
Our code coverage guide explains the theory and other types. Here we stay practical.
Install pytest-cov
pip install pytest-cov
This installs coverage.py as a dependency and adds the --cov family of options to pytest. Install it into your project’s virtual environment so CI and your laptop use the same version.
Your first coverage report
Here is a small module with a shipping rule:
# shipping.py
def shipping_cost(weight_kg, express=False, country="IN"):
if weight_kg <= 0:
raise ValueError("weight must be positive")
cost = 40 if weight_kg <= 1 else 40 + (weight_kg - 1) * 25
if express:
cost *= 2
if country != "IN":
cost += 300
return round(cost, 2)
def free_shipping(total):
if total >= 499:
return True
return False
And three tests that look reasonable:
def test_light_parcel():
assert shipping_cost(0.5) == 40
def test_express_heavy():
assert shipping_cost(3, express=True) == 180
def test_free_shipping():
assert free_shipping(600) is True
Run them with coverage:
pytest --cov=shipping --cov-report=term-missing
Name Stmts Miss Cover Missing
-------------------------------------------
shipping.py 13 3 77% 3, 8, 14
-------------------------------------------
TOTAL 13 3 77%
Reading the missing lines
The Missing column is the most useful part of the report. Each number is a line that never ran:
- Line 3: the
ValueErrorfor zero or negative weight. No test sends a bad weight. - Line 8: the international surcharge. Every test ships within India.
- Line 14:
return False. No test checks a small order.
So 77% is not an abstract number. It is three named gaps, each a real behaviour nobody has verified. Pass --cov= the package or module you are testing, not your tests folder, or the tests themselves inflate the figure.
Turn on branch coverage
pytest --cov=shipping --cov-branch --cov-report=term-missing
Name Stmts Miss Branch BrPart Cover Missing
---------------------------------------------------------
shipping.py 13 3 8 3 71% 3, 8, 14
---------------------------------------------------------
TOTAL 13 3 8 3 71%
Two new columns appear. Branch counts possible branch outcomes (8 here), and BrPart counts decisions where only some outcomes were taken (3 here). The total drops to 71% because branch coverage is stricter. We recommend always switching it on.
Why 100% line coverage can still miss a branch
This tiny function shows the reason:
# label.py
def label(order):
tag = "standard"
if order.get("express"):
tag = "express"
return tag
# test_label.py
def test_express():
assert label({"express": True}) == "express"
Line coverage only:
label.py 5 0 100%
With --cov-branch:
Name Stmts Miss Branch BrPart Cover Missing
label.py 5 0 2 1 86% 3->5
Every line ran, so line coverage reports 100%. But the if on line 3 was never false, so the jump straight from line 3 to line 5 (shown as 3->5) never happened. The standard order path is untested. Bugs love these invisible paths, such as an if without an else that should have set a default.
Enforce a minimum with fail-under
pytest --cov=shipping --cov-branch --cov-fail-under=90
FAIL Required test coverage of 90% not reached. Total coverage: 71.43%
3 passed in 0.22s
All three tests passed, yet the command exited with code 1, which we confirmed with echo $?. That is exactly what you want in CI: the build fails when coverage slips. We then added three tests for the gaps, a zero weight with pytest.raises(ValueError), an international parcel and a small order:
Name Stmts Miss Branch BrPart Cover Missing
---------------------------------------------------------
shipping.py 13 0 8 0 100%
---------------------------------------------------------
TOTAL 13 0 8 0 100%
Required test coverage of 90% reached. Total coverage: 100.00%
6 passed in 0.24s
Put the settings in pyproject.toml
Typing long flags gets old. Move them into configuration so every run, local or CI, behaves the same:
[tool.pytest.ini_options]
addopts = "--cov=shipping --cov-branch --cov-report=term-missing --cov-report=html"
[tool.coverage.report]
fail_under = 90
show_missing = true
exclude_also = ["if __name__ == .__main__.:"]
With this file in place, a plain pytest printed the report, wrote the HTML folder and confirmed Required test coverage of 90.0% reached. The [tool.coverage.*] sections are read by coverage.py itself, so they also apply if you run coverage run -m pytest without the plugin.
HTML and XML reports
--cov-report=htmlwriteshtmlcov/index.html. Open it in a browser to see each file with missed lines in red and partial branches in yellow. It is the fastest way to explore gaps.--cov-report=xmlwritescoverage.xmlin Cobertura format, which CI dashboards and services such as Codecov and SonarQube read.--cov-report=with no value turns off the terminal report when you only want files.
You can pass --cov-report several times to get several formats in one run.
Excluding code on purpose
Some lines are not worth testing, such as debug helpers or if __name__ == "__main__": blocks. Exclude them explicitly:
- Add
# pragma: no coverto a line or block header. - Use
exclude_alsoin config for patterns, as shown above. - Use
omitunder[tool.coverage.run]to skip whole files, such as migrations.
Be honest with exclusions. Excluding hard code to hit a target hides risk instead of removing it.
Tip: running tests in parallel with pytest-xdist? pytest-cov combines the data from each worker for you, so the same --cov flags still work.
Coverage in CI
A typical GitHub Actions step is a single command:
- run: pytest --cov=src --cov-branch --cov-report=xml --cov-fail-under=85
The step fails when coverage falls below 85%, and the XML file can be uploaded as an artifact or sent to a coverage service for pull request comments. Our GitHub Actions CI/CD guide shows the full workflow file.
What coverage target should you set?
There is no magic number. Many teams pick 80% to 90% for application code and higher for critical libraries. More important than the number:
- Do not let it fall. Set fail-under near today’s figure and raise it over time.
- Read the missing lines in every pull request, especially error handling.
- Remember coverage is not correctness. A test that calls a function without asserting anything still counts as coverage. Mutation testing checks whether your assertions would actually catch a bug.
Common pytest-cov problems
“Module was never imported” and “No data was collected”
We misspelled the target as --cov=shiping and got two warnings:
CoverageWarning: Module shiping was never imported. (module-not-imported)
CoverageWarning: No data was collected. (no-data-collected)
The tests still passed, so this is easy to miss in a long CI log. Check that the --cov value matches the importable package name, not a folder path with slashes. In a src/ layout, pass the package name, for example --cov=myapp.
Code imported before coverage starts
Lines that run at import time, such as module-level constants, can show as missed if something imports your package before pytest-cov starts measuring. A common cause is another plugin or a top-level import in conftest.py. pytest-cov starts as early as it can, but if the numbers look oddly low for module-level lines, check the import order.
Different numbers locally and in CI
Usually the two runs test different files, use different settings or skip different tests by marker. Keep every option in pyproject.toml instead of the CI command line, and see our pytest markers guide for how skipped groups affect totals.
Final thoughts
Pytest coverage with pytest-cov takes one install and one flag, and it turns “I think we test that” into a list of exact line numbers. Always add --cov-branch, read the Missing column, store settings in pyproject.toml, and use --cov-fail-under to stop coverage from quietly slipping. Then use those reports to find untested behaviour, not just to chase a percentage.
FAQ
How do I check code coverage in pytest?
Install pytest-cov and run pytest with the cov option pointing at your package, plus cov-report term-missing to list the lines that never ran.
What is the difference between line and branch coverage?
Line coverage counts lines that ran. Branch coverage also checks that each decision went both ways, so it catches untested paths that line coverage misses.
How do I fail a build when coverage is too low?
Add cov-fail-under with a percentage, or set fail_under in the coverage config. Pytest then exits with code 1 when total coverage is below the limit.
Does 100 percent coverage mean my code has no bugs?
No. Coverage shows what ran, not whether results were checked. Weak assertions or missing cases can still hide bugs.
How do I exclude code from coverage?
Add a pragma no cover comment to the line, use exclude_also patterns in the report config, or omit whole files in the run config.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.