Coverage.py ¶

$ python3 -m pip install coverage
For more details, see Installation.
Use coverage run to 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”.
python something.py becomes coverage run something.py
python -m amodule becomes coverage run -m amodule
Other instructions for specific test runners:
pytest
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.
unittest
Change “python” to “coverage run”, so this:
$ python -m unittest discover
becomes:
$ coverage run -m unittest discover
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.
Use coverage report to 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 html to 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.
It can produce reports in a number of formats: text,
HTML, XML, LCOV,
and JSON.
For advanced uses, there’s an API, and the result data is
available in a SQLite database.
Using coverage.py¶
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.
Some test runners provide coverage integration to make it easy to use
coverage.py while running tests.  For example, pytest has the pytest-cov
plugin.
You can fine-tune coverage.py’s view of your code by directing it to ignore
parts that you know aren’t interesting.  See Specifying source files and Excluding code from coverage.py
for details.
Getting help¶
If the FAQ doesn’t answer your question, you can discuss
coverage.py or get help using it on the Python discussion forums.  If you
ping me (@nedbat), there’s a higher chance I’ll see the post.
Bug reports are gladly accepted at the GitHub issue tracker.
GitHub also hosts the code repository.
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:
@[email protected].
More information¶
Installation
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
Plug-ins
Contributing to coverage.py
Things that cause trouble
FAQ and other help
Change history
Migrating between versions
Sleepy Snake