Coverage.py is a tool for measuring code coverage of Python programs. It monitors your program, noting which parts of the code have been executed, then analyzes the source to identify code that could have been executed but was not.
Coverage measurement is typically used to gauge the effectiveness of tests. It can show which parts of your code are being exercised by tests, and which are not.
The latest version is coverage.py 7.3.1, released September 6, 2023. It is supported on:
Python versions 3.8 through 3.12.0rc1.
PyPy3 versions 3.8 through 3.10.
Available as part of the Tidelift Subscription.
Coverage and thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use. If you want the flexibility of open source and the confidence of commercial-grade software, this is for you. Learn more.
Getting started is easy:
$ python3 -m pip install coverage
For more details, see Installation.
coverage runto run your test suite and gather data. However you normally run your test suite, you can use your test runner under coverage.
If your test runner command starts with “python”, just replace the initial “python” with “coverage run”.
coverage run something.py
python -m amodulebecomes
coverage run -m amodule
Other instructions for specific test runners:
If you usually use:
$ pytest arg1 arg2 arg3
then you can run your tests under coverage with:
$ coverage run -m pytest arg1 arg2 arg3
Many people choose to use the pytest-cov plugin, but for most purposes, it is unnecessary.
Change “python” to “coverage run”, so this:
$ python3 -m unittest discover
$ coverage run -m unittest discover
Nose has been unmaintained since at least 2015. You should seriously consider using a different test runner.
$ nosetests arg1 arg2
$ coverage run -m nose arg1 arg2
To limit coverage measurement to code in the current directory, and also find files that weren’t executed at all, add the
--source=.argument to your coverage command line.
coverage reportto report on the results:
$ coverage report -m Name Stmts Miss Cover Missing ------------------------------------------------------- my_program.py 20 4 80% 33-35, 39 my_other_module.py 56 6 89% 17-23 ------------------------------------------------------- TOTAL 76 10 87%
For a nicer presentation, use
coverage htmlto get annotated HTML listings detailing missed lines:
$ coverage html
Then open htmlcov/index.html in your browser, to see a report like this.
Coverage.py can do a number of things:
By default it will measure line (statement) coverage.
It can also measure branch coverage.
It can tell you what tests ran which lines.
There are a few different ways to use coverage.py. The simplest is the command line, which lets you run your program and see the results. If you need more control over how your project is measured, you can use the API.
Professional support for coverage.py is available as part of the Tidelift Subscription.
I can be reached in a number of ways. I’m happy to answer questions about using coverage.py.
For news and other chatter, follow the project on Mastodon: @firstname.lastname@example.org.
- For enterprise
- Command line usage
- Configuration reference
- Specifying source files
- Excluding code from coverage.py
- Branch coverage measurement
- Measuring sub-processes
- Measurement contexts
- Coverage.py API
- How coverage.py works
- Contributing to coverage.py
- Things that cause trouble
- FAQ and other help
- Change history
- Migrating between versions
- Sleepy Snake