diff options
| -rw-r--r-- | TODO.txt | 9 | ||||
| -rw-r--r-- | doc/branch.rst | 39 | ||||
| -rw-r--r-- | doc/cmd.rst | 20 | ||||
| -rw-r--r-- | doc/config.rst | 7 | ||||
| -rw-r--r-- | doc/excluding.rst | 6 | ||||
| -rw-r--r-- | doc/index.rst | 7 |
6 files changed, 64 insertions, 24 deletions
@@ -5,15 +5,6 @@ Coverage TODO + warn if no data was collected - tie --source into reporting -* 3.5b1 - -- Update changes.rst -- Document partial branch exclusion -- Document HTML reporting - - Keyboard shortcuts - - Delta reporting - - * Soon + Better omit handling that ignores files during measurement. diff --git a/doc/branch.rst b/doc/branch.rst index 2607bfdb..40e0a066 100644 --- a/doc/branch.rst +++ b/doc/branch.rst @@ -6,6 +6,7 @@ Branch coverage measurement :history: 20091127T201300, new for version 3.2 :history: 20100725T211700, updated for 3.4. +:history: 20110604T181700, updated for 3.5. .. highlight:: python :linenothreshold: 5 @@ -30,7 +31,7 @@ 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. +jump from line 2 to line 4. This is known as a partial branch. How to measure branch coverage @@ -86,18 +87,34 @@ Because the ``else`` clause is excluded, the ``if`` only has one possible next line, so it isn't considered a branch at all. -Problems --------- +Structurally partial branches +----------------------------- -Some Python constructs are difficult to measure properly. For example, an -unconditional loop will be marked as partially executed:: +Sometimes branching constructs are used in unusual ways that don't actually +branch. For example:: - while True: # line 1 - if some_condition(): # 2 + while True: + if cond: break - body_of_loop() # 4 + do_something() - keep_working() # 6 +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 partial + 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 partial" pragma indicates that the branch is known to be partial, and +the line is not flagged. -Because the loop never terminates naturally (jumping from line 1 to 6), -coverage.py considers the branch partially executed. diff --git a/doc/cmd.rst b/doc/cmd.rst index ecc24ba1..0a7c6279 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -92,6 +92,18 @@ If you are measuring coverage in a multi-process program, or across a number of machines, you'll want the ``--parallel-mode`` switch to keep the data separate during measurement. See :ref:`cmd_combining` below. +During execution, coverage.py may warn you about conditions it detects that +could affect the measurement process. The possible warnings include: + +* "Trace function changed, measurement is likely wrong" + +* "Module has no Python source" + +* "Module was never imported" + +* "No data was collected" + + .. _cmd_datafile: @@ -213,12 +225,20 @@ Lines are highlighted green for executed, red for missing, and gray for excluded. The counts at the top of the file are buttons to turn on and off the highlighting. +A number of keyboard shortcuts are available for navigating the report. +Click the keyboard icon in the upper right to see the complete list. + The ``-d`` argument specifies an output directory, defaulting to "htmlcov":: $ coverage html -d coverage_html Other common reporting options are described above in :ref:`cmd_reporting`. +Generating the HTML report can be time-consuming. Stored with the HTML report +is a data file that is used to speed up reporting the next time. If you +generate a new report into the same directory, coverage.py will skip +generating unchanged pages, making the process faster. + .. _cmd_annotation: diff --git a/doc/config.rst b/doc/config.rst index 15d38745..ddaf22a3 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -7,6 +7,7 @@ Configuration files :history: 20100223T201600, new for 3.3 :history: 20100725T211700, updated for 3.4. :history: 20100824T092900, added ``precision``. +:history: 20110604T184400, updated for 3.5. Coverage.py options can be specified in a configuration file. This makes it @@ -122,6 +123,12 @@ in reporting. See :ref:`source` for details. ``omit`` (multi-string): a list of filename patterns, the files to leave out of reporting. See :ref:`source` for details. +``partial_branches`` (multi-string): a list of regular expressions. Any line +of code that matches one of these regexes is excused from being reported as +a partial branch. More details are in :ref:`branch`. If you use this option, +you are replacing all the partial branch regexes so you'll need to also +supply the "pragma: no branch" regex if you still want to use it. + ``precision`` (integer): the number of digits after the decimal point to display for reported coverage percentages. The default is 0, displaying for example "87%". A value of 2 will display percentages like "87.32%". diff --git a/doc/excluding.rst b/doc/excluding.rst index 466f56a7..9a3b5e7d 100644 --- a/doc/excluding.rst +++ b/doc/excluding.rst @@ -7,6 +7,7 @@ Excluding code from coverage :history: 20090613T090500, brand new docs. :history: 20100224T200900, updated for 3.3. :history: 20100725T211700, updated for 3.4. +:history: 20110604T184400, updated for 3.5. You may have code in your project that you know won't be executed, and you want @@ -76,7 +77,7 @@ all of them by adding a regex to the exclusion list:: [report] exclude_lines = def __repr__ -Here's a list of exclusions I've used:: +For example, here's a list of exclusions I've used:: [report] exclude_lines = @@ -93,6 +94,9 @@ Note that when using the ``exclude_lines`` option in a configuration file, you are taking control of the entire list of regexes, so you need to re-specify the default "pragma: no cover" match if you still want it to apply. +A similar pragma, "no partial", can be used to tailor branch coverage +measurement. See :ref:`branch` for details. + Excluding source files ---------------------- diff --git a/doc/index.rst b/doc/index.rst index bec2f1bf..a5136f3e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -17,6 +17,7 @@ coverage.py :history: 20100906T134700, updated for 3.4b2. :history: 20100919T163500, updated for 3.4 release. :history: 20110213T081200, claim true 3.2 compatibility. +:history: 20110604T114800, update for 3.5b1 Coverage.py is a tool for measuring code coverage of Python programs. It monitors your program, noting which parts of the code have been executed, then @@ -26,8 +27,8 @@ Coverage measurement is typically used to gauge the effectiveness of tests. It can show which parts of your code are being exercised by tests, and which are not. -The latest version is 3.4, released 19 September 2010. -It is supported on Python 2.3 through 3.2. +The latest version is 3.5b1, released ?? June 2011 +It is supported on Python versions 2.3 through 3.2. Quick start @@ -39,7 +40,7 @@ Getting started is easy: or by using "easy_install coverage". For a few more details, see :ref:`install`. -#. Use ``coverage run`` to execute your program and gather data: +#. Use ``coverage run`` to run your program and gather data: .. code-block:: console |