doc/config.rst

   1 .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
   2 .. For details: https://bitbucket.org/ned/coveragepy/src/default/NOTICE.txt
   3
   4 .. _config:
   5
   6 ===================
   7 Configuration files
   8 ===================
   9
  10 .. :history: 20100223T201600, new for 3.3
  11 .. :history: 20100725T211700, updated for 3.4.
  12 .. :history: 20100824T092900, added ``precision``.
  13 .. :history: 20110604T184400, updated for 3.5.
  14 .. :history: 20110827T212700, updated for 3.5.1
  15 .. :history: 20130926T222300, updated for 3.6.1
  16 .. :history: 20140925T064700, updated for 4.0a1
  17 .. :history: 20150124T173400, updated for 4.0a4
  18 .. :history: 20150802T174600, updated for 4.0b1
  19
  20 .. module:: coverage
  21
  22 Coverage.py options can be specified in a configuration file.  This makes it
  23 easier to re-run coverage.py with consistent settings, and also allows for
  24 specification of options that are otherwise only available in the
  25 :ref:`API <api>`.
  26
  27 Configuration files also make it easier to get coverage testing of spawned
  28 sub-processes.  See :ref:`subprocess` for more details.
  29
  30 The default name for configuration files is ``.coveragerc``, in the same
  31 directory coverage.py is being run in.  Most of the settings in the
  32 configuration file are tied to your source code and how it should be measured,
  33 so it should be stored with your source, and checked into source control,
  34 rather than put in your home directory.
  35
  36 A different name for the configuration file can be specified with the
  37 ``--rcfile=FILE`` command line option.
  38
  39 Coverage.py will read settings from a ``setup.cfg`` file if no other
  40 configuration file is used.  In this case, the section names have "coverage:"
  41 prefixed, so the ``[run]`` options described below will be found in the
  42 ``[coverage:run]`` section of ``setup.cfg``.
  43
  44
  45 Syntax
  46 ------
  47
  48 A coverage.py configuration file is in classic .ini file format: sections are
  49 introduced by a ``[section]`` header, and contain ``name = value`` entries.
  50 Lines beginning with ``#`` or ``;`` are ignored as comments.
  51
  52 Strings don't need quotes. Multi-valued strings can be created by indenting
  53 values on multiple lines.
  54
  55 Boolean values can be specified as ``on``, ``off``, ``true``, ``false``, ``1``,
  56 or ``0`` and are case-insensitive.
  57
  58 Environment variables can be substituted in by using dollar signs: ``$WORD``
  59 or ``${WORD}`` will be replaced with the value of ``WORD`` in the environment.
  60 A dollar sign can be inserted with ``$$``.  Missing environment variables
  61 will result in empty strings with no error.
  62
  63 Many sections and values correspond roughly to commands and options in
  64 the :ref:`command-line interface <cmd>`.
  65
  66 Here's a sample configuration file::
  67
  68     # .coveragerc to control coverage.py
  69     [run]
  70     branch = True
  71
  72     [report]
  73     # Regexes for lines to exclude from consideration
  74     exclude_lines =
  75         # Have to re-enable the standard pragma
  76         pragma: no cover
  77
  78         # Don't complain about missing debug-only code:
  79         def __repr__
  80         if self\.debug
  81
  82         # Don't complain if tests don't hit defensive assertion code:
  83         raise AssertionError
  84         raise NotImplementedError
  85
  86         # Don't complain if non-runnable code isn't run:
  87         if 0:
  88         if __name__ == .__main__.:
  89
  90     ignore_errors = True
  91
  92     [html]
  93     directory = coverage_html_report
  94
  95
  96 .. _config_run:
  97
  98 [run]
  99 -----
 100
 101 These values are generally used when running product code, though some apply
 102 to more than one command.
 103
 104 ``branch`` (boolean, default False): whether to measure
 105 :ref:`branch coverage <branch>` in addition to statement coverage.
 106
 107 ``cover_pylib`` (boolean, default False): whether to measure the Python
 108 standard library.
 109
 110 ``concurrency`` (multi-string, default "thread"): the name concurrency
 111 libraries in use by the product code.  If your program uses `multiprocessing`_,
 112 `gevent`_, `greenlet`_, or `eventlet`_, you must name that library in this
 113 option, or coverage.py will produce very wrong results.
 114
 115 .. _multiprocessing: https://docs.python.org/2/library/multiprocessing.html
 116 .. _greenlet: http://greenlet.readthedocs.org/en/latest/
 117 .. _gevent: http://www.gevent.org/
 118 .. _eventlet: http://eventlet.net/
 119
 120 Before version 4.2, this option only accepted a single string.
 121
 122 .. versionadded:: 4.0
 123
 124 ``data_file`` (string, default ".coverage"): the name of the data file to use
 125 for storing or reporting coverage. This value can include a path to another
 126 directory.
 127
 128 ``debug`` (multi-string): a list of debug options.  See :ref:`the run
 129 --debug option <cmd_run_debug>` for details.
 130
 131 ``include`` (multi-string): a list of file name patterns, the files to include
 132 in measurement or reporting.  See :ref:`source` for details.
 133
 134 ``note`` (string): an arbitrary string that will be written to the data file.
 135 You can use the :meth:`CoverageData.run_infos` method to retrieve this string
 136 from a data file.
 137
 138 ``omit`` (multi-string): a list of file name patterns, the files to leave out
 139 of measurement or reporting.  See :ref:`source` for details.
 140
 141 ``parallel`` (boolean, default False): append the machine name, process
 142 id and random number to the data file name to simplify collecting data from
 143 many processes.  See :ref:`cmd_combining` for more information.
 144
 145 ``plugins`` (multi-string): a list of plugin package names. See :ref:`plugins`
 146 for more information.
 147
 148 ``source`` (multi-string): a list of packages or directories, the source to
 149 measure during execution.  See :ref:`source` for details.
 150
 151 ``timid`` (boolean, default False): use a simpler but slower trace method.
 152 Try this if you get seemingly impossible results.
 153
 154
 155 .. _config_paths:
 156
 157 [paths]
 158 -------
 159
 160 The entries in this section are lists of file paths that should be considered
 161 equivalent when combining data from different machines::
 162
 163     [paths]
 164     source =
 165         src/
 166         /jenkins/build/*/src
 167         c:\myproj\src
 168
 169 The names of the entries are ignored, you may choose any name that you like.
 170 The value is a lists of strings.  When combining data with the ``combine``
 171 command, two file paths will be combined if they start with paths from the same
 172 list.
 173
 174 The first value must be an actual file path on the machine where the reporting
 175 will happen, so that source code can be found.  The other values can be file
 176 patterns to match against the paths of collected data, or they can be absolute
 177 or relative file paths on the current machine.
 178
 179 See :ref:`cmd_combining` for more information.
 180
 181
 182 .. _config_report:
 183
 184 [report]
 185 --------
 186
 187 Values common to many kinds of reporting.
 188
 189 ``exclude_lines`` (multi-string): a list of regular expressions.  Any line of
 190 your source code that matches one of these regexes is excluded from being
 191 reported as missing.  More details are in :ref:`excluding`.  If you use this
 192 option, you are replacing all the exclude regexes, so you'll need to also
 193 supply the "pragma: no cover" regex if you still want to use it.
 194
 195 ``fail_under`` (integer): a target coverage percentage. If the total coverage
 196 measurement is under this value, then exit with a status code of 2.
 197
 198 ``ignore_errors`` (boolean, default False): ignore source code that can't be
 199 found, emitting a warning instead of an exception.
 200
 201 ``include`` (multi-string): a list of file name patterns, the files to include
 202 in reporting.  See :ref:`source` for details.
 203
 204 ``omit`` (multi-string): a list of file name patterns, the files to leave out
 205 of reporting.  See :ref:`source` for details.
 206
 207 ``partial_branches`` (multi-string): a list of regular expressions.  Any line
 208 of code that matches one of these regexes is excused from being reported as
 209 a partial branch.  More details are in :ref:`branch`.  If you use this option,
 210 you are replacing all the partial branch regexes so you'll need to also
 211 supply the "pragma: no branch" regex if you still want to use it.
 212
 213 ``precision`` (integer): the number of digits after the decimal point to
 214 display for reported coverage percentages.  The default is 0, displaying for
 215 example "87%".  A value of 2 will display percentages like "87.32%".
 216
 217 ``show_missing`` (boolean, default False): when running a summary report, show
 218 missing lines.  See :ref:`cmd_summary` for more information.
 219
 220 ``skip_covered`` (boolean, default False): Don't include files in the report
 221 that are 100% covered files. See :ref:`cmd_summary` for more information.
 222
 223 ``sort`` (string, default "Name"): Sort the text report by the named column.
 224 Allowed values are "Name", "Stmts", "Miss", "Branch", "BrPart", or "Cover".
 225
 226
 227 .. _config_html:
 228
 229 [html]
 230 ------
 231
 232 Values particular to HTML reporting.  The values in the ``[report]`` section
 233 also apply to HTML output, where appropriate.
 234
 235 ``directory`` (string, default "htmlcov"): where to write the HTML report files.
 236
 237 ``extra_css`` (string): the path to a file of CSS to apply to the HTML report.
 238 The file will be copied into the HTML output directory.  Don't name it
 239 "style.css".  This CSS is in addition to the CSS normally used, though you can
 240 overwrite as many of the rules as you like.
 241
 242 ``title`` (string, default "Coverage report"): the title to use for the report.
 243 Note this is text, not HTML.
 244
 245
 246 .. _config_xml:
 247
 248 [xml]
 249 -----
 250
 251 Values particular to XML reporting.  The values in the ``[report]`` section
 252 also apply to XML output, where appropriate.
 253
 254 ``output`` (string, default "coverage.xml"): where to write the XML report.
 255
 256 ``package_depth`` (integer, default 99): controls which directories are
 257 identified as packages in the report.  Directories deeper than this depth are
 258 not reported as packages.  The default is that all directories are reported as
 259 packages.