doc/howitworks.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 .. _howitworks:
   5
   6 =====================
   7 How Coverage.py works
   8 =====================
   9
  10 .. :history: 20150812T071000, new page.
  11
  12 For advanced use of coverage.py, or just because you are curious, it helps to
  13 understand what's happening behind the scenes.  Coverage.py works in three
  14 phases:
  15
  16 * **Execution**: Coverage.py runs your code, and monitors it to see what lines
  17   were executed.
  18
  19 * **Analysis**: Coverage.py examines your code to determine what lines could
  20   have run.
  21
  22 * **Reporting**: Coverage.py combines the results of execution and analysis to
  23   produce a coverage number and an indication of missing execution.
  24
  25 The execution phase is handled by the ``coverage run`` command.  The analysis
  26 and reporting phases are handled by the reporting commands like ``coverage
  27 report`` or ``coverage html``.
  28
  29 Let's look at each phase in more detail.
  30
  31
  32 Execution
  33 ---------
  34
  35 At the heart of the execution phase is a Python trace function.  This is a
  36 function that the Python interpreter invokes for each line executed in a program.
  37 Coverage.py implements a trace function that records each file and line number
  38 as it is executed.
  39
  40 Executing a function for every line in your program can make execution very
  41 slow.  Coverage.py's trace function is implemented in C to reduce that
  42 slowdown. It also takes care to not trace code that you aren't interested in.
  43
  44 When measuring branch coverage, the same trace function is used, but instead of
  45 recording line numbers, coverage.py records pairs of line numbers.  Each
  46 invocation of the trace function remembers the line number, then the next
  47 invocation records the pair `(prev, this)` to indicate that execution
  48 transitioned from the previous line to this line.  Internally, these are called
  49 arcs.
  50
  51 For more details of trace functions, see the Python docs for `sys.settrace`_,
  52 or if you are really brave, `How C trace functions really work`_.
  53
  54 At the end of execution, coverage.py writes the data it collected to a data
  55 file, usually named ``.coverage``.  This is a JSON-based file containing all of
  56 the recorded file names and line numbers executed.
  57
  58 .. _sys.settrace: https://docs.python.org/3/library/sys.html#sys.settrace
  59 .. _How C trace functions really work: http://nedbatchelder.com/text/trace-function.html
  60
  61
  62 Analysis
  63 --------
  64
  65 After your program has been executed and the line numbers recorded, coverage.py
  66 needs to determine what lines could have been executed.  Luckily, compiled
  67 Python files (.pyc files) have a table of line numbers in them.  Coverage.py
  68 reads this table to get the set of executable lines, with a little more source
  69 analysis to leave out things like docstrings.
  70
  71 The data file is read to get the set of lines that were executed.  The
  72 difference between the executable lines, and the executed lines, are the lines
  73 that were not executed.
  74
  75 The same principle applies for branch measurement, though the process for
  76 determining possible branches is more involved.  Coverage.py uses the abstract
  77 syntax tree of the Python source file to determine the set of possible
  78 branches.
  79
  80
  81 Reporting
  82 ---------
  83
  84 Once we have the set of executed lines and missing lines, reporting is just a
  85 matter of formatting that information in a useful way.  Each reporting method
  86 (text, html, annotated source, xml) has a different output format, but the
  87 process is the same: write out the information in the particular format,
  88 possibly including the source code itself.
  89
  90
  91 Plugins
  92 -------
  93
  94 Plugins interact with these phases.