doc/excluding.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 .. _excluding:
   5
   6 ===============================
   7 Excluding code from coverage.py
   8 ===============================
   9
  10 .. :history: 20090613T090500, brand new docs.
  11 .. :history: 20100224T200900, updated for 3.3.
  12 .. :history: 20100725T211700, updated for 3.4.
  13 .. :history: 20110604T184400, updated for 3.5.
  14
  15
  16 You may have code in your project that you know won't be executed, and you want
  17 to tell coverage.py to ignore it.  For example, you may have debugging-only
  18 code that won't be executed during your unit tests. You can tell coverage.py to
  19 exclude this code during reporting so that it doesn't clutter your reports with
  20 noise about code that you don't need to hear about.
  21
  22 Coverage.py will look for comments marking clauses for exclusion.  In this
  23 code, the "if debug" clause is excluded from reporting::
  24
  25     a = my_function1()
  26     if debug:   # pragma: no cover
  27         msg = "blah blah"
  28         log_message(msg, a)
  29     b = my_function2()
  30
  31 Any line with a comment of "pragma: no cover" is excluded.  If that line
  32 introduces a clause, for example, an if clause, or a function or class
  33 definition, then the entire clause is also excluded.  Here the __repr__
  34 function is not reported as missing::
  35
  36     class MyObject(object):
  37         def __init__(self):
  38             blah1()
  39             blah2()
  40
  41         def __repr__(self): # pragma: no cover
  42             return "<MyObject>"
  43
  44 Excluded code is executed as usual, and its execution is recorded in the
  45 coverage data as usual. When producing reports though, coverage.py excludes it
  46 from the list of missing code.
  47
  48
  49 Branch coverage
  50 ---------------
  51
  52 When measuring :ref:`branch coverage <branch>`, a conditional will not be
  53 counted as a branch if one of its choices is excluded::
  54
  55     def only_one_choice(x):
  56         if x:
  57             blah1()
  58             blah2()
  59         else:       # pragma: no cover
  60             # x is always true.
  61             blah3()
  62
  63 Because the ``else`` clause is excluded, the ``if`` only has one possible next
  64 line, so it isn't considered a branch at all.
  65
  66
  67 Advanced exclusion
  68 ------------------
  69
  70 Coverage.py identifies exclusions by matching lines against a list of regular
  71 expressions. Using :ref:`configuration files <config>` or the coverage
  72 :ref:`API <api>`, you can add to that list. This is useful if you have
  73 often-used constructs to exclude that can be matched with a regex. You can
  74 exclude them all at once without littering your code with exclusion pragmas.
  75
  76 For example, you might decide that __repr__ functions are usually only used in
  77 debugging code, and are uninteresting to test themselves.  You could exclude
  78 all of them by adding a regex to the exclusion list::
  79
  80     [report]
  81     exclude_lines = def __repr__
  82
  83 For example, here's a list of exclusions I've used::
  84
  85     [report]
  86     exclude_lines =
  87         pragma: no cover
  88         def __repr__
  89         if self.debug:
  90         if settings.DEBUG
  91         raise AssertionError
  92         raise NotImplementedError
  93         if 0:
  94         if __name__ == .__main__.:
  95
  96 Note that when using the ``exclude_lines`` option in a configuration file, you
  97 are taking control of the entire list of regexes, so you need to re-specify the
  98 default "pragma: no cover" match if you still want it to apply.
  99
 100 A similar pragma, "no branch", can be used to tailor branch coverage
 101 measurement.  See :ref:`branch` for details.
 102
 103
 104 Excluding source files
 105 ----------------------
 106
 107 See :ref:`source` for ways to limit what files coverage.py measures or reports
 108 on.