ThisCalculator

Everyday

Pytest Coverage Report: Generate It in 5 Steps

Updated · Standard formula, shown below

This guide shows you how to generate a pytest code coverage report, which tells you which lines of your code are actually executed during tests and which are not. You’ll learn to create a terminal summary, an HTML report you can open in a browser, and an XML report for CI tools. You’ll need a Python project with pytest already installed and at least one test file.

What You’ll Need

  • Python 3.7 or newer installed on your system
  • pytest installed (check with pytest --version)
  • The pytest-cov plugin installed (we’ll install it in Step 1)
  • A project directory containing your source code and tests

Step-by-Step

  1. Install pytest-cov
    Open a terminal and run:
    pip install pytest-cov
    This plugin adds coverage options to the pytest command. Verify it’s recognized by running pytest --help and looking for --cov in the output.
  2. Run pytest with basic coverage
    From your project root, run:
    pytest --cov=your_package_name
    Replace your_package_name with the name of the module or package you want to measure (e.g., --cov=src if your code lives in a src folder). If you have multiple packages, list them separated by commas or use --cov=. to include everything in the current directory.
  3. Read the terminal summary
    After the test results, you’ll see a table with columns: Stmts (total statements), Miss (statements not executed), Branch (branch coverage if enabled), BrPart (partial branches), Cover (percentage covered). The final line shows the total coverage percentage.
  4. Generate an HTML report
    Run:
    pytest --cov=your_package_name --cov-report=html
    This creates a htmlcov/ directory. Open htmlcov/index.html in a browser to see a color-coded view of each file. Green lines are executed, red lines are missed, and yellow lines indicate partial branches.
  5. Generate an XML report (for CI)
    For tools like Jenkins or GitLab CI, run:
    pytest --cov=your_package_name --cov-report=xml
    This produces a coverage.xml file in the project root, which CI systems can parse to track coverage over time.
  6. Combine multiple report types
    You can generate several reports at once:
    pytest --cov=your_package_name --cov-report=term --cov-report=html --cov-report=xml
  7. Set a coverage threshold (optional)
    To fail the build if coverage drops below a percentage, add --cov-fail-under=80 (replace 80 with your desired minimum).

Common Mistakes

  • Forgetting the package name – Running pytest --cov without a target measures nothing and often errors. Always specify --cov=your_package.
  • Measuring the wrong directory – If your code is in a src folder but you run --cov=., you’ll include tests and configuration files, skewing the numbers.
  • Ignoring missing dependencies – The plugin must be installed in the same environment where you run pytest. If you use a virtual environment, install it there.
  • Not excluding test files – Coverage will count your test files as part of the codebase unless you exclude them. Use --cov=your_package to target only the source code, or add --cov-report=term --cov=your_package to avoid including tests.
  • Misreading the coverage percentage – 80% coverage means 80% of statements were executed, not that 80% of branches were tested. Branch coverage is separate and requires --cov-branch.

Tips

  • Enable branch coverage – Run pytest --cov=your_package --cov-branch to see how many if/else paths are tested. This gives a more thorough picture.
  • Use a config file – Add coverage settings to pyproject.toml or .coveragerc to avoid typing long commands. For example, in pyproject.toml under [tool.coverage.run], set branch = true and source = ["your_package"].
  • Generate a diff report – Use --cov-report=term-missing to show which lines are missing in the terminal output, so you don’t have to open the HTML.
  • Integrate with pre-commit – Add a coverage threshold to your CI pipeline to prevent regressions. For example, --cov-fail-under=90.
  • Clean old reports – The htmlcov folder can become stale. Delete it before regenerating to avoid confusion.

Troubleshooting

  • “ModuleNotFoundError: No module named ‘pytest_cov’” – The plugin isn’t installed. Run pip install pytest-cov and ensure you’re in the correct virtual environment.
  • “No data to report” – This usually means the package you specified doesn’t exist or wasn’t imported by any test. Double-check the package name and that your tests actually import the code.
  • Coverage shows 0% for all files – Your tests aren’t importing the code. Make sure your test files import the modules you’re measuring, and that the package path is correct.
  • HTML report is outdated – Delete the htmlcov folder and rerun the command. The report is not automatically cleaned.
  • Coverage percentage is too low – Look at the missing lines in the terminal or HTML. Often it’s because you haven’t tested error paths or edge cases. Write more tests for those branches.
  • Command works locally but fails in CI – Ensure the CI environment has pytest-cov installed and that you’re running the command from the project root where the package is importable.

Frequently Asked Questions

What is the difference between statement and branch coverage?

Statement coverage tells you which lines of code ran. Branch coverage tells you which if/else or loop branches were taken. Branch coverage is stricter and often reveals untested edge cases.

Can I exclude certain files from coverage?

Yes. Use --cov=your_package to only measure that package, or add omit patterns in a .coveragerc file, e.g., omit = */migrations/*.

How do I see which lines are missing in the terminal?

Add --cov-report=term-missing to your command. The terminal output will then show line numbers for missed statements.

Does coverage affect the test results?

No. Coverage measurement is passive; it only records which lines execute. Your tests run exactly the same way. However, adding coverage tracking can slightly slow down execution.

What is a good coverage percentage?

There’s no universal number. Many projects aim for 80-90% for critical code, but the right target depends on your domain. Focus on covering the most important logic rather than chasing a number.

Can I generate coverage for a single test file?

Yes. Run pytest test_file.py --cov=your_package to measure coverage only when running that specific test file. This is useful for debugging a particular module.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.