diff options
| -rw-r--r-- | doc/cmd.rst | 37 | ||||
| -rw-r--r-- | doc/excluding.rst | 66 | ||||
| -rw-r--r-- | doc/faq.rst | 55 | ||||
| -rw-r--r-- | doc/index.rst | 31 |
4 files changed, 174 insertions, 15 deletions
diff --git a/doc/cmd.rst b/doc/cmd.rst index 4d49e3f0..0a9f0f68 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -128,8 +128,39 @@ decorated to show the status of each line. Here's a `sample report </code/coverage/sample_html/index.html>`_. +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. -Annotation ----------- +The -d argument to specify an output directory is required:: -text annotation too! + $ coverage -b -d covhtml + + +Text Annotation +--------------- + +The -a flag produces a text annotation of your source code. With a -d argument +specifying an output directory, each Python file becomes a text file in that +directory. Without -d, the files are written into the same directories as the +original Python files. + +Coverage status for each line of source is indicated with a character prefix:: + + > executed + ! missing (not executed) + - excluded + +For example:: + + # A simple function, never called with x==1 + + > def h(x): + """Silly function.""" + - if 0: #pragma: no cover + - pass + > if x == 1: + ! a = 1 + > else: + > a = 2 + diff --git a/doc/excluding.rst b/doc/excluding.rst new file mode 100644 index 00000000..d336813b --- /dev/null +++ b/doc/excluding.rst @@ -0,0 +1,66 @@ +.. _excluding: + +============================ +Excluding code from coverage +============================ + +:history: 20090613T090500, brand new docs. + +You may have code in your project that you know won't be executed, and you want +to tell coverage to ignore it. For example, you may have debugging-only code +that won't be executed during your unit tests. You can tell coverage to exclude +this code during reporting so that it doesn't clutter your reports with noise +about code that you don't need to hear about. + +Coverage will look for comments marking clauses for exclusion. In this code, +the "if debug" clause is excluded from reporting:: + + a = my_function1() + if debug: # pragma: no cover + msg = "blah blah" + log_message(msg, a) + b = my_function2() + +Any line with a comment of "pragma: no cover" is excluded. If that line +introduces a clause, for example, an if clause, or a function or class +definition, then the entire clause is also excluded. Here the __repr__ +function is not reported as missing:: + + class MyObject(object): + def __init__(self): + blah1() + blah2() + + def __repr__(self): # pragma: no cover + return "<MyObject>" + +Excluded code is executed as usual, and its execution is recorded in the +coverage data as usual. When producing reports though, coverage excludes it from +the list of missing code. + + +Advanced exclusion +------------------ + +Coverage identifies exclusions by matching lines against a list of regular +expressions. Using the coverage :ref:`API <api>`, you can add to that list. +This is useful if you have often-used constructs to exclude that can be matched +with a regex. You can exclude them all at once without littering your code with +exclusion pragmas. + +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__") + +Here's a list of exclusions I've used:: + + coverage.exclude('def __repr__') + coverage.exclude('if self.debug:') + coverage.exclude('if settings.DEBUG') + coverage.exclude('raise AssertionError') + coverage.exclude('raise NotImplementedError') + coverage.exclude('if 0:') + coverage.exclude('if __name__ == .__main__.:') + diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 00000000..364ed998 --- /dev/null +++ b/doc/faq.rst @@ -0,0 +1,55 @@ +.. _faq: + +================== +FAQ and Other Help +================== + +:history: 20090613T141800, brand new docs. + +Frequently Asked Questions +-------------------------- + +**Q: Why do unexecutable lines show up as executed?** + +Usually this is because you've updated your code and run coverage on it +again without erasing the old data. Coverage records line numbers executed, so +the old data may have recorded a line number which has since moved, causing +coverage to claim a line has been executed which cannot be. + +Use the -e switch on the command line to erase all data before starting the next +run. + +**Q: Why do the bodies of functions (or classes) show as executed, but the def +lines do not?** + +This happens because coverage is started after the functions are defined. The +definition lines are executed without coverage measurement, then coverage is +started, then the function is called. This means the body is measured, but +the definition of the function itself is not. + +To fix this, start coverage earlier. If you use the :ref:`command line <cmd>` +to run your program with coverage, then your entire program will be monitored. +If you are using the :ref:`API <api>`, you need to call coverage.start() before +importing the modules that define your functions. + +**Q: Does coverage work on Python 3.0?** + +Not yet, but that's next on my list. + +**Q: Isn't coverage testing the best thing ever?** + +It's good, but `it isn't perfect +<http://nedbatchelder.com/blog/200710/flaws_in_coverage_measurement.html>`_. + + +Getting More Help +----------------- + +You can discuss coverage or get help using it on the `Testing In Python +<http://lists.idyll.org/listinfo/testing-in-python>`_ mailing list. + +Bug reports are gladly accepted at the `bitbucket issue tracker +<http://bitbucket.org/ned/coveragepy/issues/>`_. + +Lastly, `I can be reached <http://nedbatchelder.com/site/aboutned.html>`_ in a +number of ways. diff --git a/doc/index.rst b/doc/index.rst index a4cd1f17..221c06a1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,9 +4,9 @@ coverage.py :history: 20090524T134300, brand new docs.
-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 analyzes the
-source to identify code that could have been executed but was not.
+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
+analyzes the source to identify code that could have been executed but was not.
Quick Start
@@ -16,8 +16,8 @@ Getting started with coverage.py is easy: #. Install coverage.py from the
`coverage page on the cheeseshop <http://pypi.python.org/pypi/coverage>`_,
- or by using "easy_install coverage". You may need to install the python-dev
- support files, for example with "apt-get install python-dev".
+ or by using "easy_install coverage". You may need to install the
+ python-dev support files, for example with "apt-get install python-dev".
#. Run coverage to execute your program and gather data:
@@ -58,9 +58,20 @@ 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>`
+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>`_.
+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.
+
+
+History
+-------
+
+Coverage.py was originally written by `Gareth Rees <http://garethrees.org/>`_.
+Ned Batchelder has maintained and extended it since 2004.
+
More information
----------------
@@ -70,14 +81,10 @@ More information cmd
api
+ excluding
+ faq
changes
-.. FAQ
-.. Why do unexecutable lines show up as executed?
-.. Why do the bodies of fns show as executed, but the def lines do not?
-.. Change History
-.. Getting Help
.. How it works
.. .coverage file format
-.. Excluding lines
|