For Enterprise

Available as part of the Tidelift Subscription.
Coverage and thousands of other packages are working withTidelift to deliver one enterprise subscription that covers all of the opensource you use. If you want the flexibility of open source and the confidenceof commercial-grade software, this is for you.Learn more.

Quick start

Getting started is easy:

1. Install coverage.py:

   $ python3 -m pip install coverage

   For more details, seeInstallation.

2. Usecoveragerun to run your test suite and gather data. However younormally run your test suite, you can use your test runner under coverage.

   Tip

   If your test runner command starts with “python”, replace the initial“python” with “coverage run”.

   pythonsomething.py becomescoveragerunsomething.py

   python-mamodule becomescoveragerun-mamodule

   Other instructions for specific test runners:

   • pytest
   • unittest
   • nosetest

   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 thepytest-cov plugin, but for mostpurposes, it is unnecessary.

   Change your python command name to “coverage run”, so this:

   $ python3 -m unittest discover

   becomes:

   $ coverage run -m unittest discover

   Note

   Nose has beenunmaintained since at least 2015.You should seriously consider using a different test runner.

   Change this:

   $ nosetests arg1 arg2

   to:

   $ coverage run -m nose arg1 arg2

   Coverage doesn’t distinguish between tests and the code being tested.Werecommend that you include your tests in coverage measurement.

   To limit coverage measurement to code in the current directory, and alsofind files that weren’t executed at all, add the--source=. argument toyour coverage command line. You can alsospecify source files tomeasure orexclude code from measurement.

3. Usecoveragereport to report on the results:

   $ coverage report -mName                      Stmts   Miss  Cover   Missing-------------------------------------------------------my_program.py                20      4    80%   33-35, 39my_other_module.py           56      6    89%   17-23-------------------------------------------------------TOTAL                        76     10    87%

4. For a nicer presentation, usecoveragehtml to get annotated HTMLlistings detailing missed lines:

   $ coverage htmlWrote HTML report to htmlcov/index.html

   Then openhtmlcov/index.html in your browserto see areport like this.

Capabilities

Coverage.py can do a number of things:

• By default it will measure line (statement) coverage.

• It can also measurebranch coverage.

• It can tell youwhat tests ran which lines.

• It can produce reports in a number of formats:text,HTML,XML,LCOV,andJSON.

• For advanced uses, there’s anAPI, and the result data isavailable in aSQLite database.

Using coverage.py

There are a few different ways to use coverage.py. The simplest is thecommand 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 theAPI.

Some test runners provide coverage integration to make it easy to usecoverage.py while running tests. For example,pytest has thepytest-covplugin.

You can fine-tune coverage.py’s view of your code by directing it to ignoreparts that you know aren’t interesting. SeeSpecifying source files andExcluding code from coverage.pyfor details.

Getting help

If theFAQ doesn’t answer your question, you can discusscoverage.py or get help using it on thePython discussion forums or in thePython Discord. If you ping me (@nedbat), there’s a higher chance I’llsee the post.

Bug reports are gladly accepted at theGitHub issue tracker.GitHub also hosts thecode repository.

Professional support for coverage.py is available as part of theTideliftSubscription.

I can be reached in a number of ways. I’m happy to answer questions aboutusing coverage.py.

For news and other chatter, follow the project on Mastodon:@coveragepy@hachyderm.io.

More information