Package: z3c.coverage
This package contains tools to work with Python coverage data.coveragereportproduces HTML reports from coverage data, with
syntax-highlighted source code and per-package aggregate numbers.coveragediffcompares two sets of coverage reports and reports
regressions, that is, increases in the number of untested lines of code.ContentsUsing coveragereportUsing coveragediffGetting coverage datazope.testrunnercoverage.pytrace.pyFrequently Asked QuestionsWhy use z3c.coverage instead of coverage html?Should I use zope.testrunner’s built-in coverage, or coverage run bin/test?Did anyone actually ask any of these questions?Changes2.1.0 (2017-04-24)2.0.3 (2015-11-09)2.0.2 (2013-10-01)2.0.1 (2013-10-01)2.0.0 (2013-02-20)1.3.1 (2012-10-24)1.3.0 (2012-09-06)1.2.0 (2010-02-11)1.1.3 (2009-07-24)1.1.2 (2008-04-14)1.1.1 (2008-01-31)1.1.0 (2008-01-29)1.0.1 (2007-09-26)1.0.0 (2007-09-26)0.2.10.2.00.1.0Using coveragereport$ coveragereport --help
Usage: coveragereport [options] [inputpath [outputdir]]

Converts coverage reports to HTML.  If the input path is omitted, it defaults
to coverage or .coverage, whichever exists.  If the output directory is
omitted, it defaults to inputpath + /report or ./coverage-reports, depending
on whether the input path points to a directory or a file.

Options:
  -h, --help            show this help message and exit
  -q, --quiet           be quiet
  -v, --verbose         be verbose (default)
  --strip-prefix=PREFIX
                        strip base directory from filenames loaded from
                        .coverage
  --path-alias=PATH=LOCALPATH
                        define path mappings for filenames loaded from
                        .coverageExample use withzope.testrunner:$ bin/test --coverage=coverage
$ coveragereport
$ ln -s mypackage.html coverage/report/index.html
$ xdg-open coverage/report/index.html
$ xdg-open coverage/report/all.htmlExample use withnoseandcoverage.py:$ nosetests --with-coverage --cover-erase
$ coveragereport --strip-prefix=/full/path/to/source/
$ ln -s mypackage.html coverage-reports/index.html
$ xdg-open coverage-reports/index.html
$ xdg-open coverage-reports/all.htmlSample report:NoteYou needenscriptinstalled and available in your$PATHif you want syntax
highlighting.Using coveragediffUsage: coveragediff [options] olddir newdir

Options:
  -h, --help         show this help message and exit
  --include=REGEX    only consider files matching REGEX
  --exclude=REGEX    ignore files matching REGEX
  --email=ADDR       send the report to a given email address (only if
                     regressions were found)
  --from=ADDR        set the email sender address
  --subject=SUBJECT  set the email subject
  --web-url=BASEURL  include hyperlinks to HTML-ized coverage reports at a
                     given URLUsage example withzope.testrunner:$ bin/test --coverage=coverage
$ vi src/...
$ mv coverage coverage.old
$ bin/test --coverage=coverage
$ coveragediff coverage.old coverageYou cannot usecoveragediffwithcoverage.pydata.  More on that below.Output example:$ coveragediff coverage.old coverage
my.package.module: 36 new lines of untested code
my.package.newmodule: new file with 15 lines of untested code (out of 23)Output with clickable links:$ coveragediff coverage.old coverage --web-url=http://example.com/coverage
my.package.module: 36 new lines of untested code
See http://example.com/coverage/my.package.module.html

my.package.newmodule: new file with 15 lines of untested code (out of 23)
See http://example.com/coverage/my.package.newmodule.htmlOutput via email, convenient for continuous integration:$ coveragediff coverage.old coverage --web-url=http://example.com/coverage \
                   --email 'Developers <dev@exmaple.com>' \
                   --from 'Buildbot <buildbot@example.com>'That last example doesn’t produce any output, but sends an email (via SMTP
to localhost:25).Getting coverage datazope.testrunnerzope.testrunnercan
produce a directory full of files nameddotted.package.name.coverthat contain source code annotated with coverage information.  To get
them, usebin/test --coverage=outdir/Bothcoveragereportandcoveragediffaccept this as inputs.coverage.pycoverage.pycan produce
a.coveragefile containing (incomplete) coverage information.  To get it,
usecoverage run bin/testrunnercoveragereportcan take the.coveragefile as an input, but it
also needs access to the matching source files.  And you have to manually
specify the absolute pathname prefix of your source tree so that the
report know how to translate filenames into dotted package names.  Also,
it’s not enough to haveabsolutepathnames, you need to supply thecanonicalabsolute pathname (with no symlink segments), such as returned
byos.path.realpath.  This is very inconvenient.  Sorry.coveragediffis unable to compare two.coveragefiles and report
regressions.  One reason for that is the incompleteness of the data format
(it line numbers of executed statements, but doesn’t say which lines contain
code and which ones are blank/comments/continuation lines/excluded source
lines).  The other reason is simpler: nobody wrote the code.;)Unfortunatelycoverage annotatedoes not produce files compatible
withcoveragereport/coveragediff.  This could also be remedied
if somebody wrote a patch.NoteIf you want to use a.coveragefile produced on another machine
or simply in a different working directory, you will need to
tellcoveragereporthow to adjust the absolute filenames so that
the sources can be found.  Use the--path-aliasoption for that.
Alternatively you could usecoverage combineto manipulate the.coveragefile itself, as described in the documentation.trace.pyThe*.coverannotated-source format produced byzope.testrunneractually comes from the Python standard library moduletrace.py.  You can probably use trace.py
directly.  I’ve never tried.Frequently Asked QuestionsWhy use z3c.coverage instead of coverage html?Some people prefer the look of the reports produced by z3c.coverage.
Some people find per-package coverage summaries or the tree-like navigation
convenient.Should I use zope.testrunner’s built-in coverage, or coverage run bin/test?coverage.pyismuchfaster, but using it (and hooking it up to z3c.coverage)
is perhaps less convenient.  E.g. if you usezc.buildout 1.5.xwithzc.recipe.testrunner, you will be unable to usecoverage run bin/testbecause of mystic semi-broken site isolation magic of the former.Did anyone actually ask any of these questions?Does asking myself count?Changes2.1.0 (2017-04-24)Support (and require) coverage.py >= 4.0.Fix incorrect highlighting of missed lines when processing coverage.py data
(broken since 2.0.2).Dropped Python 2.6 support.Added Python 3.4, 3.5 and 3.6 support.2.0.3 (2015-11-09)Standardize namespace __init__.2.0.2 (2013-10-01)Bug: coveragereport now also accepts non-ASCII chars in source files
(also fix the case when enscript is not available).2.0.1 (2013-10-01)Bug: coveragereport now also accepts non-ASCII chars in source files.2.0.0 (2013-02-20)Added Python 3.3 and PyPy 1.9 support.Dropped Python 2.4 and 2.5 support.1.3.1 (2012-10-24)Nicer PyPI description.  Doctests are tests, not docs.coveragereportnow accepts--path-alias.coveragereport: new color step between yellow (90%) and green (100%), a
yellowish-green (95%).1.3.0 (2012-09-06)coveragereportnow accepts--help,--verboseand--quietoptions, with verbose being on by default.coveragereportnow can handle .coverage files produced byhttp://pypi.python.org/pypi/coverageBugfix: sorting by numbered of uncovered lines was broken in theall.htmlreport.1.2.0 (2010-02-11)Rename thecoveragescript tocoveragereport, to avoid name clashes
with Ned Batchelder’s excellent coverage.py.1.1.3 (2009-07-24)Bug: Doctest did not normalize the whitespace incoveragediff.txt. For
some reason it passes while testing independently, but when running all
tests, it failed.1.1.2 (2008-04-14)Bug: When a package path contained anywhere the word “test”, it was ignored
from the coverage report. The intended behavior, however, was to ignore
files that relate to setting up tests.Bug: Sort the results ofos.listdir()inREADME.txtto avoid
non-deterministic failures.Bug: The logic for ignoring unit and functional test modules also used to
ignore modules and packages calledtesting.Change “Unit test coverage” to “Test coverage” in the title – it works
perfectly fine for functional tests too.1.1.1 (2008-01-31)Bug: When the package was released, the test which tests the availability of
an SVN revision number failed. Made the test more reliable.1.1.0 (2008-01-29)Feature: Themain()coverage report function now accepts the arguments
of the script as a function argument, making it easier to configure the
script from buildout.Feature: When the report directory does not exist, the report generator
creates it for you.Feature: Eat your own dog food by creating a buildout that can create
coverage reports.Bug: Improved the test coverage to 100%.1.0.1 (2007-09-26)Bug: Fixed meta-data.1.0.0 (2007-09-26)First public release.0.2.1Feature: Added the--weboption tocoveragediff.Feature: Added a test suite.0.2.0Feature: Addedcoveragediff.py.0.1.0Initial release ofcoveragereport.py.