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