Add coverage

tools/telemetry/third_party/coverage/doc/branch.rst

+.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+.. For details: https://bitbucket.org/ned/coveragepy/src/default/NOTICE.txt
+
+.. _branch:
+
+===========================
+Branch coverage measurement
+===========================
+
+.. :history: 20091127T201300, new for version 3.2
+.. :history: 20100725T211700, updated for 3.4.
+.. :history: 20110604T181700, updated for 3.5.
+.. :history: 20111214T181800, Fix a bug that Guido pointed out.
+
+.. highlight:: python
+   :linenothreshold: 5
+
+
+In addition to the usual statement coverage, coverage.py also supports branch
+coverage measurement. Where a line in your program could jump to more than one
+next line, coverage.py tracks which of those destinations are actually visited,
+and flags lines that haven't visited all of their possible destinations.
+
+For example::
+
+    def my_partial_fn(x):       # line 1
+        if x:                   #      2
+            y = 10              #      3
+        return y                #      4
+
+    my_partial_fn(1)
+
+In this code, line 2 is an ``if`` statement which can go next to either line 3
+or line 4. Statement coverage would show all lines of the function as executed.
+But the if was never evaluated as false, so line 2 never jumps to line 4.
+
+Branch coverage will flag this code as not fully covered because of the missing
+jump from line 2 to line 4.  This is known as a partial branch.
+
+
+How to measure branch coverage
+------------------------------
+
+To measure branch coverage, run coverage.py with the ``--branch`` flag::
+
+    coverage run --branch myprog.py
+
+When you report on the results with ``coverage report`` or ``coverage html``,
+the percentage of branch possibilities taken will be included in the percentage
+covered total for each file.  The coverage percentage for a file is the actual
+executions divided by the execution opportunities.  Each line in the file is an
+execution opportunity, as is each branch destination.
+
+The HTML report gives information about which lines had missing branches. Lines
+that were missing some branches are shown in yellow, with an annotation at the
+far right showing branch destination line numbers that were not exercised.
+
+The XML report produced by ``coverage xml`` also includes branch information,
+including separate statement and branch coverage percentages.
+
+
+How it works
+------------
+
+When measuring branches, coverage.py collects pairs of line numbers, a source
+and destination for each transition from one line to another.  Static analysis
+of the compiled bytecode provides a list of possible transitions.  Comparing
+the measured to the possible indicates missing branches.
+
+The idea of tracking how lines follow each other was from `Titus Brown`__.
+Thanks, Titus!
+
+__ http://ivory.idyll.org/blog
+
+
+Excluding code
+--------------
+
+If you have :ref:`excluded code <excluding>`, a conditional will not be counted
+as a branch if one of its choices is excluded::
+
+    def only_one_choice(x):
+        if x:
+            blah1()
+            blah2()
+        else:       # pragma: no cover
+            # x is always true.
+            blah3()
+
+Because the ``else`` clause is excluded, the ``if`` only has one possible next
+line, so it isn't considered a branch at all.
+
+
+Structurally partial branches
+-----------------------------
+
+Sometimes branching constructs are used in unusual ways that don't actually
+branch.  For example::
+
+    while True:
+        if cond:
+            break
+        do_something()
+
+Here the while loop will never exit normally, so it doesn't take both of its
+"possible" branches.  For some of these constructs, such as "while True:" and
+"if 0:", coverage.py understands what is going on.  In these cases, the line
+will not be marked as a partial branch.
+
+But there are many ways in your own code to write intentionally partial
+branches, and you don't want coverage.py pestering you about them.  You can
+tell coverage.py that you don't want them flagged by marking them with a
+pragma::
+
+    i = 0
+    while i < 999999999:    # pragma: no branch
+        if eventually():
+            break
+
+Here the while loop will never complete because the break will always be taken
+at some point.  Coverage.py can't work that out on its own, but the "no branch"
+pragma indicates that the branch is known to be partial, and the line is not
+flagged.