diff options
| -rw-r--r-- | coverage/control.py | 6 | ||||
| -rw-r--r-- | doc/branch.rst | 46 | ||||
| -rw-r--r-- | doc/excluding.rst | 2 | ||||
| -rw-r--r-- | doc/index.rst | 27 |
4 files changed, 41 insertions, 40 deletions
diff --git a/coverage/control.py b/coverage/control.py index 4bcb4ed4..24fed7b9 100644 --- a/coverage/control.py +++ b/coverage/control.py @@ -30,8 +30,7 @@ class coverage(object): def __init__(self, data_file=None, data_suffix=False, cover_pylib=False, auto_data=False, timid=False, branch=False): - """Create a new coverage measurement context. - + """ `data_file` is the base name of the data file to use, defaulting to ".coverage". `data_suffix` is appended to `data_file` to create the final file name. If `data_suffix` is simply True, then a suffix is @@ -49,7 +48,8 @@ class coverage(object): used. This is important for some environments where manipulation of tracing functions breaks the faster trace function. - If `branch` is true, then measure branch execution. + If `branch` is true, then branch coverage will be measured in addition + to the usual statement coverage. """ from coverage import __version__ diff --git a/doc/branch.rst b/doc/branch.rst index 19be019a..1966b45d 100644 --- a/doc/branch.rst +++ b/doc/branch.rst @@ -18,20 +18,18 @@ For example:: my_partial_fn(1) -In this code, the if on line 2 could branch to either line 3 or line 4. -Statement coverage would show all lines of the function as executed. But the -if is always true, so line 2 never jumps to line 4. Even though line 4 is -executed, coverage.py knows that it was never because of a branch from line -2. +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 would flag this code as not fully covered because of the -missing jump from line 2 to line 4. +Branch coverage will flag this code as not fully covered because of the missing +jump from line 2 to line 4. How to measure branch coverage ------------------------------ -To measure branch coverage, run coverage.py with the --branch flag:: +To measure branch coverage, run coverage.py with the ``--branch`` flag:: coverage run --branch myprog.py @@ -41,10 +39,13 @@ 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. -Currently, only HTML reports give 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 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. Each line is +annotated with How it works @@ -59,11 +60,15 @@ The idea of tracking how lines follow each other was from C. Titus Brown. Thanks, Titus! +Excluding code +-------------- + +If you have excluded Problems -------- Some Python constructs are difficult to measure properly. For example, an -infinite loop will be marked as partially executed:: +unconditional loop will be marked as partially executed:: while True: # line 1 if some_condition(): # 2 @@ -73,17 +78,4 @@ infinite loop will be marked as partially executed:: keep_working() # 6 Because the loop never terminates naturally (jumping from line 1 to 6), -coverage.py thinks the branch is partially executed. - -Currently, if you exclude code from coverage testing, a branch into that code -will still be considered executable, and may result in the branch being -flagged. - - -Other work ----------- - -One interesting side effect of tracking line transitions: we know where some -exceptions happened because a transition happens that wasn't predicted by the -static analysis. Currently, I'm not doing anything with this information. -Any ideas? +coverage.py considers the branch partially executed. diff --git a/doc/excluding.rst b/doc/excluding.rst index 0dfee514..1072e5b1 100644 --- a/doc/excluding.rst +++ b/doc/excluding.rst @@ -52,7 +52,7 @@ For example, you might decide that __repr__ functions are usually only used in debugging code, and are uninteresting to test themselves. You could exclude all of them by adding a regex to the exclusion list:: - coverage.exclude("def __repr__") + coverage.exclude('def __repr__') Here's a list of exclusions I've used:: diff --git a/doc/index.rst b/doc/index.rst index 10a92a59..80295304 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -8,6 +8,7 @@ coverage.py :history: 20090707T205200, changes for 3.0.1
:history: 20090913T084400, new command line syntax
:history: 20091004T211900, version 3.1
+:history: 20091127T155100, version 3.2
Coverage.py is a tool for measuring code coverage of Python programs. It
@@ -18,8 +19,8 @@ Coverage measurement is typically used to gauge the effectiveness of tests. It can show which parts of your product code are being exercised by tests, and
which are not.
-The latest version is 3.1, released 4 October 2009. It is supported on Python
-2.3 through 3.1.
+The latest version is 3.2, released ?? November 2009.
+It is supported on Python 2.3 through 3.1.
Quick start
@@ -27,11 +28,12 @@ Quick start Getting started is easy:
-#. Install coverage.py from the
- `coverage page on the cheeseshop <http://pypi.python.org/pypi/coverage>`_,
+#. Install coverage.py from the `coverage page on the Python Package Index`__,
or by using "easy_install coverage". You may need to install the
python-dev support files, for example with "apt-get install python-dev".
+__ http://pypi.python.org/pypi/coverage
+
#. Use ``coverage run`` to execute your program and gather data:
.. code-block:: console
@@ -59,7 +61,9 @@ Getting started is easy: $ coverage html -d htmlcov
Then visit htmlcov/index.html in your browser, to see a
- `report like this </code/coverage/sample_html/index.html>`_.
+ `report like this`__.
+
+__ /code/coverage/sample_html/index.html
Using coverage.py
@@ -71,20 +75,24 @@ If you need more control over how your project is measured, you can use the :ref:`API <api>`.
Some test runners provide coverage integration to make it easy to use coverage
-while running tests. For example, `nose <http://somethingaboutorange.com/mrl/projects/nose>`_
-has a `cover plug-in <http://somethingaboutorange.com/mrl/projects/nose/0.11.1/plugins/cover.html>`_.
+while running tests. For example, `nose`_ has a `cover plug-in`_.
You can fine-tune coverage's view of your code by directing it to ignore parts
that you know aren't interesting. See :ref:`Excluding Code <excluding>` for
details.
+.. _nose: http://somethingaboutorange.com/mrl/projects/nose
+.. _cover plug-in: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/plugins/cover.html
+
History
-------
-Coverage.py was originally written by `Gareth Rees <http://garethrees.org/>`_.
-Ned Batchelder has maintained and extended it since 2004.
+Coverage.py was originally written by `Gareth Rees`_.
+Since 2004, `Ned Batchelder`_ has maintained and extended it.
+.. _Gareth Rees: http://garethrees.org/
+.. _Ned Batchelder: http://nedbatchelder.com
More information
@@ -96,6 +104,7 @@ More information cmd
api
excluding
+ branch
faq
changes
|