1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
===========
Coverage.py
===========
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 |release|, released |release_date|. It is
supported on:
.. PYVERSIONS
* Python versions 3.7 through 3.12.0a7.
* PyPy3 7.3.11.
.. ifconfig:: prerelease
**This is a pre-release build. The usual warnings about possible bugs
apply.** The latest stable version is coverage.py 6.5.0, `described here`_.
.. _described here: http://coverage.readthedocs.io/
For Enterprise
--------------
.. image:: media/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White.png
:width: 75
:alt: Tidelift
:align: left
:class: tideliftlogo
:target: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=readme
`Available as part of the Tidelift Subscription. <Tidelift Subscription_>`_ |br|
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. <Tidelift
Subscription_>`_
.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=docs
Quick start
-----------
Getting started is easy:
#. Install coverage.py::
$ python3 -m pip install coverage
For more details, see :ref:`install`.
#. 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.
.. tip::
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:
.. tabs::
.. tab:: 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.
.. tab:: unittest
Change "python" to "coverage run", so this::
$ python -m unittest discover
becomes::
$ coverage run -m unittest discover
.. tab:: nosetest
*Nose has been unmaintained for a long time. You should seriously
consider adopting a different test runner.*
Change this::
$ nosetests arg1 arg2
to::
$ 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.
#. 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
.. ifconfig:: not prerelease
Then open htmlcov/index.html in your browser, to see a
`report like this`_.
.. ifconfig:: prerelease
Then open htmlcov/index.html in your browser, to see a
`report like this one`_.
.. _report like this: https://nedbatchelder.com/files/sample_coverage_html/index.html
.. _report like this one: https://nedbatchelder.com/files/sample_coverage_html_beta/index.html
Capabilities
------------
Coverage.py can do a number of things:
- By default it will measure line (statement) coverage.
- It can also measure :ref:`branch coverage <branch>`.
- It can tell you :ref:`what tests ran which lines <dynamic_contexts>`.
- It can produce reports in a number of formats: :ref:`text <cmd_report>`,
:ref:`HTML <cmd_html>`, :ref:`XML <cmd_xml>`, :ref:`LCOV <cmd_lcov>`,
and :ref:`JSON <cmd_json>`.
- For advanced uses, there's an :ref:`API <api>`, and the result data is
available in a :ref:`SQLite database <dbschema>`.
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.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 :ref:`source` and :ref:`excluding`
for details.
.. _pytest: http://doc.pytest.org
.. _pytest-cov: https://pytest-cov.readthedocs.io/
.. _contact:
Getting help
------------
If the :ref:`FAQ <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.
.. _Python discussion forums: https://discuss.python.org/
Bug reports are gladly accepted at the `GitHub issue tracker`_.
GitHub also hosts the `code repository`_.
.. _GitHub issue tracker: https://github.com/nedbat/coveragepy/issues
.. _code repository: https://github.com/nedbat/coveragepy
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.
.. _I can be reached: https://nedbatchelder.com/site/aboutned.html
.. raw:: html
<p>For news and other chatter, follow the project on Mastodon:
<a rel="me" href="https://hachyderm.io/@coveragepy">@coveragepy@hachyderm.io</a>.</p>
More information
----------------
.. toctree::
:maxdepth: 1
install
For enterprise <https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=enterprise>
cmd
config
source
excluding
branch
subprocess
contexts
api
howitworks
plugins
contributing
trouble
faq
Change history <changes>
migrating
sleepy
|
