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
|
.. _config:
===================
Configuration files
===================
.. :history: 20100223T201600, new for 3.3
.. :history: 20100725T211700, updated for 3.4.
.. :history: 20100824T092900, added ``precision``.
.. :history: 20110604T184400, updated for 3.5.
.. :history: 20110827T212700, updated for 3.5.1
.. :history: 20130926T222300, updated for 3.6.1
.. :history: 20140925T064700, updated for 4.0a1
.. :history: 20150124T173400, updated for 4.0a4
Coverage.py options can be specified in a configuration file. This makes it
easier to re-run coverage with consistent settings, and also allows for
specification of options that are otherwise only available in the
:ref:`API <api>`.
Configuration files also make it easier to get coverage testing of spawned
sub-processes. See :ref:`subprocess` for more details.
The default name for configuration files is ``.coveragerc``, in the same
directory coverage.py is being run in. Most of the settings in the
configuration file are tied to your source code and how it should be measured,
so it should be stored with your source, and checked into source control,
rather than put in your home directory.
A different name for the configuration file can be specified with the
``--rcfile=FILE`` command line option.
Coverage.py will read settings from a ``setup.cfg`` file if no other
configuration file is used. In this case, the section names have "coverage:"
prefixed, so the ``[run]`` options described below will be found in the
``[coverage:run]`` section of ``setup.cfg``.
Syntax
------
A coverage.py configuration file is in classic .ini file format: sections are
introduced by a ``[section]`` header, and contain ``name = value`` entries.
Lines beginning with ``#`` or ``;`` are ignored as comments.
Strings don't need quotes. Multi-valued strings can be created by indenting
values on multiple lines.
Boolean values can be specified as ``on``, ``off``, ``true``, ``false``, ``1``,
or ``0`` and are case-insensitive.
Environment variables can be substituted in by using dollar signs: ``$WORD``
or ``${WORD}`` will be replaced with the value of ``WORD`` in the environment.
A dollar sign can be inserted with ``$$``. Missing environment variables
will result in empty strings with no error.
Many sections and values correspond roughly to commands and options in
the :ref:`command-line interface <cmd>`.
Here's a sample configuration file::
# .coveragerc to control coverage.py
[run]
branch = True
[report]
# Regexes for lines to exclude from consideration
exclude_lines =
# Have to re-enable the standard pragma
pragma: no cover
# Don't complain about missing debug-only code:
def __repr__
if self\.debug
# Don't complain if tests don't hit defensive assertion code:
raise AssertionError
raise NotImplementedError
# Don't complain if non-runnable code isn't run:
if 0:
if __name__ == .__main__.:
ignore_errors = True
[html]
directory = coverage_html_report
.. _config_run:
[run]
-----
These values are generally used when running product code, though some apply
to more than one command.
``branch`` (boolean, default False): whether to measure
:ref:`branch coverage <branch>` in addition to statement coverage.
``cover_pylib`` (boolean, default False): whether to measure the Python
standard library.
``concurrency`` (string, default "thread"): the name of the concurrency
library in use by the product code. If your program uses `gevent`_,
`greenlet`_, or `eventlet`_, you must name that library in this option, or
coverage will produce very wrong results.
.. _greenlet: http://greenlet.readthedocs.org/en/latest/
.. _gevent: http://www.gevent.org/
.. _eventlet: http://eventlet.net/
``data_file`` (string, default ".coverage"): the name of the data file to use
for storing or reporting coverage.
``debug`` (multi-string): a list of debug options. See :ref:`the run
--debug option <cmd_run_debug>` for details.
``include`` (multi-string): a list of filename patterns, the files to include
in measurement or reporting. See :ref:`source` for details.
``omit`` (multi-string): a list of filename patterns, the files to leave out
of measurement or reporting. See :ref:`source` for details.
``parallel`` (boolean, default False): append the machine name, process
id and random number to the data file name to simplify collecting data from
many processes. See :ref:`cmd_combining` for more information.
``plugins`` (multi-string): a list of plugin package names. See :ref:`plugins`
for more information.
``source`` (multi-string): a list of packages or directories, the source to
measure during execution. See :ref:`source` for details.
``timid`` (boolean, default False): use a simpler but slower trace method.
Try this if you get seemingly impossible results.
.. _config_paths:
[paths]
-------
The entries in this section are lists of file paths that should be considered
equivalent when combining data from different machines::
[paths]
source =
src/
/jenkins/build/*/src
c:\myproj\src
The names of the entries are ignored, you may choose any name that you like.
The value is a lists of strings. When combining data with the ``combine``
command, two file paths will be combined if they start with paths from the same
list.
The first value must be an actual file path on the machine where the reporting
will happen, so that source code can be found. The other values can be file
patterns to match against the paths of collected data, or they can be absolute
or relative file paths on the current machine.
See :ref:`cmd_combining` for more information.
.. _config_report:
[report]
--------
Values common to many kinds of reporting.
``exclude_lines`` (multi-string): a list of regular expressions. Any line of
your source code that matches one of these regexes is excluded from being
reported as missing. More details are in :ref:`excluding`. If you use this
option, you are replacing all the exclude regexes, so you'll need to also
supply the "pragma: no cover" regex if you still want to use it.
``ignore_errors`` (boolean, default False): ignore source code that can't be
found.
``include`` (multi-string): a list of filename patterns, the files to include
in reporting. See :ref:`source` for details.
``omit`` (multi-string): a list of filename patterns, the files to leave out
of reporting. See :ref:`source` for details.
``partial_branches`` (multi-string): a list of regular expressions. Any line
of code that matches one of these regexes is excused from being reported as
a partial branch. More details are in :ref:`branch`. If you use this option,
you are replacing all the partial branch regexes so you'll need to also
supply the "pragma: no branch" regex if you still want to use it.
``precision`` (integer): the number of digits after the decimal point to
display for reported coverage percentages. The default is 0, displaying for
example "87%". A value of 2 will display percentages like "87.32%".
``show_missing`` (boolean, default False): when running a summary report, show
missing lines. See :ref:`cmd_summary` for more information.
``skip_covered`` (boolean, default False): when running a summary report,
skip 100% covered files. See :ref:`cmd_summary` for more information.
.. _config_html:
[html]
------
Values particular to HTML reporting. The values in the ``[report]`` section
also apply to HTML output, where appropriate.
``directory`` (string, default "htmlcov"): where to write the HTML report files.
``extra_css`` (string): the path to a file of CSS to apply to the HTML report.
The file will be copied into the HTML output directory. Don't name it
"style.css". This CSS is in addition to the CSS normally used, though you can
overwrite as many of the rules as you like.
``title`` (string, default "Coverage report"): the title to use for the report.
Note this is text, not HTML.
.. _config_xml:
[xml]
-----
Values particular to XML reporting. The values in the ``[report]`` section
also apply to XML output, where appropriate.
``output`` (string, default "coverage.xml"): where to write the XML report.
|
