coverage.py / doc / index.rst

coverage.py

history:20090524T134300, brand new docs.
history:20090613T164000, final touches for 3.0
history:20090618T195900, minor tweaks
history:20090707T205200, changes for 3.0.1
history:20090913T084400, new command line syntax
history:20091004T211900, version 3.1
history:20091127T155100, version 3.2
history:20091205T161429, version 3.2 for real.
history:20100224T204700, version 3.3
history:20100306T181500, version 3.3.1
history:20100725T211700, updated for 3.4.
history:20100820T151500, updated for 3.4b1.
history:20100906T134700, updated for 3.4b2.
history:20100919T163500, updated for 3.4 release.
history:20110213T081200, claim true 3.2 compatibility.
history:20110604T114800, update for 3.5b1
history:20110629T082300, update for 3.5
history:20110827T221800, update for 3.5.1b1
history:20110923T081800, update for 3.5.1
history:20120429T162100, updated for 3.5.2b1
history:20120503T233800, updated for 3.5.2
history:20120929T093500, updated for 3.5.3
history:20121117T094900, Change from easy_install to pip.
history:20121128T203700, Updated for 3.6b1.
history:20121223T180600, Updated for 3.6b2.
history:20121229T112300, Updated for 3.6b3.
history:20130105T174000, Updated for 3.6
history:20131005T210000, Updated for 3.7
history:20131212T213300, Updated for 3.7.1

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.

Quick start

Getting started is easy:

  1. Install coverage.py from the coverage page on the Python Package Index, or by using "pip install coverage". For a few more details, see :ref:`install`.

  2. Use coverage run to run your program and gather data:

    $ coverage run my_program.py arg1 arg2
    blah blah ..your program's output.. blah blah
    
  3. Use coverage report to report on the results:

    $ coverage report -m
    Name                      Stmts   Miss  Cover   Missing
    -------------------------------------------------------
    my_program                   20      4    80%   33-35, 39
    my_other_module              56      6    89%   17-23
    -------------------------------------------------------
    TOTAL                        76     10    87%
    
  4. For a nicer presentation, use coverage html to get annotated HTML listings detailing missed lines:

    $ coverage html
    

Using coverage.py

There are a few different ways to use coverage.py. The simplest is the :ref:`command line <cmd>`, 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 :ref:`API <api>`.

Some test runners provide coverage integration to make it easy to use coverage while running tests. For example, nose has a cover plug-in.

You can fine-tune coverage's view of your code by directing it to ignore parts that you know aren't interesting. See :ref:`source` and :ref:`excluding` for details.

Getting help

If the :ref:`FAQ <faq>` doesn't answer your question, you can discuss coverage.py or get help using it on the Testing In Python mailing list.

Bug reports are gladly accepted at the Bitbucket issue tracker. Bitbucket also hosts the code repository. There is a mirrored repo on Github.

I can be reached in a number of ways. I'm happy to answer questions about using coverage.py.

More information

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.