diff options
Diffstat (limited to 'doc/coverage.px')
| -rw-r--r-- | doc/coverage.px | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/doc/coverage.px b/doc/coverage.px new file mode 100644 index 00000000..ffc8b353 --- /dev/null +++ b/doc/coverage.px @@ -0,0 +1,250 @@ +<?xml version="1.0" encoding="utf-8" ?> +<page title='coverage'> +<history> +<what when='20041212T183900'>Created.</what> +<what when='20051204T131100'>Updated to 2.5.</what> +<what when='20060822T210600'>Updated to 2.6.</what> +<what when='20061001T164600'>Added a problem description for doctest users.</what> +<what when='20070721T211900'>Updated to 2.7.</what> +<what when='20070722T154900'>Updated to 2.75.</what> +<what when='20070723T201400'>Updated to 2.76.</what> +<what when='20070729T201400'>Updated to 2.77.</what> +<what when='20080107T071400'>Updated to 2.78.</what> +<what when='20080525T135029'>Updated to 2.8.</what> +<what when='20080525T172606'>Updated to 2.80.</what> +<what when='20081012T080912'>Updated to 2.85.</what> +</history> + +<p>Coverage.py is a Python module that measures code coverage during Python execution. +It uses the code analysis tools and tracing hooks provided in the Python standard +library to determine which lines are executable, and which have been executed. +The original version was written by +<a href='code/modules/rees-coverage.html'>Gareth Rees</a>. +I've updated it to determine executable statements more accurately. +</p> + +<h1>Installation</h1> + +<p>To install coverage, unpack the tar file, and run "setup.py install", +or use "easy_install coverage".</p> + +<download file='coverage-2.85.tar.gz' path='code/modules/coverage-2.85.tar.gz' /> + +<p>You will have a coverage module for importing, and a coverage command +for command line execution.</p> + +<p>There is also a set of tests for coverage: +<a href='code/modules/test_coverage.py'>test_coverage.py</a> and +<a href='code/modules/coverage_coverage.py'>coverage_coverage.py</a>. +These will only be of interest if you want to modify coverage.py. +</p> + +<h1>Command-line usage</h1> + +<p>The command line interface hasn't changed from the original version. +All of the +<a href='code/modules/rees-coverage.html'>original instructions</a> +still hold. +Read that document if you haven't used coverage.py before. +Here I'll describe the changes I've introduced.</p> + +<p>The identification of executable statements is now more accurate. +Docstrings are not flagged as missing statements, nor are "global" statements. +Complex multi-line if and elif conditions are handled properly. +</p> + +<p>Statements can now be excluded from consideration. This is useful if you +have lines of code that you know will not be executed, and you don't want the +coverage report to be filled with their noise. For example, you may have +interactive test clauses at the ends of your modules that your test +suite will not execute:</p> + +<code lang='python'><![CDATA[ +#.. all the real code .. + +if __name__ == '__main__': + # Run the test code from the command-line, for convenience + blah.run('sample') +]]></code> + +<p>This suite of code can be excluded from the coverage report by adding +a specially-formed comment:</p> + +<code lang='python'><![CDATA[ +#.. all the real code .. + +if __name__ == '__main__': #pragma: no cover + # Run the test code from the command-line, for convenience + blah.run('sample') +]]></code> + +<p>The #pragma line can be placed on any line of code. If the line contains the +colon that introduces a suite of statements, the entire suite is excluded. +Annotated files (created with "coverage -a") will prefix excluded lines with "-".</p> + + +<h1>Programmatic usage</h1> + +<p>Again, the +<a href='code/modules/rees-coverage.html'>original instructions</a> +still hold, but I've made a few additions.</p> + +<p>The form of the exclusion marker can be changed using the exclude() method. +It takes a regular expression, and excludes any line that contains +a match:</p> + +<code lang='python'><![CDATA[ +# Don't count branches that will never execute +coverage.exclude('if super_debug:') +]]></code> + +<p>As the example shows, the marker pattern doesn't have to be a comment. +Any number of regular expressions can be added by calling exclude a number of times.</p> + +<p>The use of a file to hold coverage data can be suppressed by calling use_cache(0) +before calling start().</p> + +<p>The analysis(module) function still returns a 4-tuple +(filename, statement list, missing list, missing string). +A new analysis2(module) function extends the return to a 5-tuple +(filename, statement list, excluded list, missing list, missing string).</p> + +<p>The annotate(modules) function is available to annotate a list of modules, and +the annotate_file(filename, statements, excluded, missing) function provides +the bulk of annotation in a directly callable form.</p> + + +<h1>Known Problems</h1> + +<p>Older versions of doctest interfere with coverage's tracing of statements, and you +may get reports that none of your code is executing. +Use <a href='http://svn.zope.org/Zope3/trunk/src/zope/testing/doctest.py?rev=28679&r1=28703&r2=28705'>this patch to doctest.py</a> +if you are experiencing problems.</p> + + +<h1>History</h1> + +<p>Changes I've made over time:</p> + +<h2>Version 2.85, September 14 2008</h2> + +<ul> + <li>Add support for finding source files in eggs.</li> + <li>Don't check for morf's being instances of ModuleType, instead use duck typing + so that pseudo-modules can participate. Thanks, Imri Goldberg.</li> + <li>Use os.realpath as part of the fixing of filenames so that symlinks won't + confuse things. Thanks, Patrick Mezard.</li> +</ul> + +<h2>Version 2.80, May 25 2008</h2> + +<ul> + <li>Coverage.py is now installed as an egg, making integration with + <a href='http://www.somethingaboutorange.com/mrl/projects/nose/'>nose</a> smoother. + If you had an older version of coverage, remove the old coverage.py in the + command directory (for example, /usr/bin or \Python25\Scripts).</li> + <li>Source files are opened in rU mode, preventing problems with errant line endings.</li> +</ul> + +<h2>Version 2.78, September 30 2007</h2> + +<ul> + <li>Better handling of Python source in files that don't end with .py. + Thanks, Ben Finney.</li> +</ul> + +<h2>Version 2.77, July 29 2007</h2> + +<ul> +<li>Better packaging, including Cheeseshop goodness.</li> +</ul> + +<h2>Version 2.76, July 23 2007</h2> + +<ul> +<li>Added support for the overlooked "with" statement in Python 2.5.</li> +</ul> + +<h2>Version 2.75, July 22 2007</h2> + +<ul> +<li>The way multi-line statements are handled has been revamped, allowing +coverage.py to support Python 2.5.</li> +<li>Functions with just a docstring and a pass statement no longer report the +pass as uncovered.</li> +</ul> + +<h2>Version 2.7, July 21 2007</h2> + +<ul> +<li>The #pragma:nocover comment syntax is ignored by default, so programmatic +invocations of coverage also attend to those declarations.</li> +<li>Constants in the middle of functions are properly ignored, since they won't be executed.</li> +<li>Code exec'ed from strings no longer clutters reports with exceptions. +That code will be ignored by coverage.py, since we can't get the source code to +analyze it anyway.</li> +<li>Minor fixes: Linux current directory handling (thanks Guillaume Chazarain), +globbing for Windows (thanks Noel O'Boyle), and Python 2.2 compatibility (thanks Catherine Proulx).</li> +</ul> + +<h2>Version 2.6, August 22 2006</h2> + +<ul> +<li>Function decorators are now handled properly (thanks Joseph Tate).</li> +<li>Fixed a few bugs with the --omit option (thanks Mark van der Wal and Sigve Tjora)</li> +<li>Coverage data files can be written from several processes at once with the -p and -c options (thanks Geoff Bache).</li> +</ul> + +<h2>Version 2.5, December 4 2005</h2> + +<ul> +<li>Multi-threaded programs now have all threads properly measured (thanks Martin Fuzzey).</li> +<li>The report() method now takes an optional file argument which defaults to stdout.</li> +<li>Adapted Greg Rogers' patch to allow omitting files by directory from the report and annotation, +sorting files, and reporting files relatively.</li> +<li>coverage.py can now recursively measure itself under test!</li> +</ul> + +<h2>Version 2.2, December 31 2004</h2> + +<ul> +<li>Made it possible to use keyword arguments with the module global functions (thanks Allen).</li> +</ul> + +<h2>Version 2.1, December 14 2004</h2> + +<ul> +<li>Fix some backward-compatibility problems with the analysis function.</li> +<li>Refactor annotate to provide annotate_file.</li> +</ul> + +<h2>Version 2, December 12 2004</h2> + +<ul> +<li>My first version.</li> +</ul> + + +<h1>Problems</h1> + +<p>Coverage.py has been tested successfully on Pythons 2.2.3, 2.3.5, 2.4.3, 2.5.1 and 2.6a3. +If you have code that it doesn't handle properly, send it to me! Be sure to mention the +version of Python you are using. +</p> + + + +<h1>See also</h1> + +<ul> +<li>Gareth Rees's <a href='code/modules/rees-design.html'>original page</a> about the design of coverage.py</li> +<li><a href='http://www.mems-exchange.org/software/sancho/'>Sancho</a> is a unit testing framework that includes code coverage measurement.</li> +<li><a href='http://www.geocities.com/drew_csillag/pycover.html'>pycover</a>, another Python implementation of code coverage.</li> +<li>The <a href='http://docs.python.org/library/trace.html'>trace module</a> in the Python standard library.</li> +<li><a href='blog'>My blog</a>, where topics often include those of interest to both casual and serious Python users.</li> +</ul> + +<googleads/> +<pagecomments/> + +</page> |