z3c.coverage 1.1.0

CoverageNode Class

This class represents a node in the source tree. Simple modules are considered leaves and do not have children. Let’s create a node for the z3c namespace first:

>>> z3cNode = coveragereport.CoverageNode()

Before using the API, let’s create a few more nodes and a tree from it:

>>> coverageNode = coveragereport.CoverageNode()
>>> z3cNode['coverage'] = coverageNode

>>> reportNode = coveragereport.CoverageNode()
>>> reportNode._covered, reportNode._total = 40, 134
>>> coverageNode['coveragereport'] = reportNode

>>> diffNode = coveragereport.CoverageNode()
>>> diffNode._covered, diffNode._total = 128, 128
>>> coverageNode['coveragediff'] = diffNode

>>> initNode = coveragereport.CoverageNode()
>>> initNode._covered, initNode._total = 0, 0
>>> coverageNode['__init__'] = initNode

Let’s now have a look at the coverage of the z3c namespace:

>>> z3cNode.coverage
(168, 262)

We can also ask for the percentile:

>>> z3cNode.percent
64
>>> initNode.percent
100

We can ask for the amoutn of uncovered lines:

>>> z3cNode.uncovered
94

Finally, we also can get a nice output:

>>> print z3cNode
64% covered (94 of 262 lines uncovered)

index_to_filename() function

Takes an indexed Python path and produces the cover filename for it:

>>> coveragereport.index_to_filename(('z3c', 'coverage', 'coveragereport'))
'z3c.coverage.coveragereport.cover'

>>> coveragereport.index_to_filename(())
''

index_to_nice_name() function

Takes an indexed Python path and produces a nice “human-readable” string:

>>> coveragereport.index_to_nice_name(('z3c', 'coverage', 'coveragereport'))
'        coveragereport'

>>> coveragereport.index_to_nice_name(())
'Everything'

index_to_name() function

Takes an indexed Python path and produces a “human-readable” string:

>>> coveragereport.index_to_name(('z3c', 'coverage', 'coveragereport'))
'z3c.coverage.coveragereport'

>>> coveragereport.index_to_name(())
'everything'

percent_to_colour() function

Given a coverage percentage, this function returns a color to represent the coverage:

>>> coveragereport.percent_to_colour(100)
'green'
>>> coveragereport.percent_to_colour(92)
'yellow'
>>> coveragereport.percent_to_colour(85)
'orange'
>>> coveragereport.percent_to_colour(50)
'red'

get_svn_revision() function

Given a path, the function tries to determine the revision number of the file. If it fails, “UNKNOWN” is returned:

>>> path = os.path.split(z3c.coverage.__file__)[0]
>>> coveragereport.get_svn_revision(path)
'8...M'

>>> coveragereport.get_svn_revision(path + '/__init__.py')
'UNKNOWN'

syntax_highlight() function

This function takes a cover file, converts it to a nicely colored HTML output:

>>> filename = os.path.join(
...     os.path.split(z3c.coverage.__file__)[0], '__init__.py')

>>> print coveragereport.syntax_highlight(filename)
<BLANKLINE>
<I><FONT COLOR="#B22222"># Make a package.
</FONT></I>

If the highlighing command is not available, no coloration is done:

>>> command_orig = coveragereport.HIGHLIGHT_COMMAND
>>> coveragereport.HIGHLIGHT_COMMAND = 'foobar %s'

>>> print coveragereport.syntax_highlight(filename)
# Make a package.
<BLANKLINE>

>>> coveragereport.HIGHLIGHT_COMMAND = command_orig

coveragereport.py is a script

For convenience you can download the coveragereport.py module and run it as a script:

>>> import sys
>>> sys.argv = ['coveragereport', inputDir, outputDir]

>>> script_file = os.path.join(
...     z3c.coverage.__path__[0], 'coveragereport.py')

>>> execfile(script_file, dict(__name__='__main__'))

Defaults are chosen, when no input and output dir is specified:

>>> def make_coverage_reports_stub(path, report_path):
...     print path
...     print report_path

>>> make_coverage_reports_orig = coveragereport.make_coverage_reports
>>> coveragereport.make_coverage_reports = make_coverage_reports_stub

>>> sys.argv = ['coveragereport']
>>> coveragereport.main()
coverage
coverage/reports

>>> coveragereport.make_coverage_reports = make_coverage_reports_orig

Links to web pages

Report printer can also include links to web pages with the coverage reports (e.g. the ones you can get from the coverage tool distributed with z3c.coverage).

>>> printer = ReportPrinter(web_url='http://example.com/coverage/')
>>> printer.warn('/tmp/coverage/z3c.coverage.coveragediff.cover',
...              '3 new untested lines')
z3c.coverage.coveragediff: 3 new untested lines
See http://example.com/coverage/z3c.coverage.coveragediff.html
<BLANKLINE>
>>> printer.warn('/tmp/coverage/z3c.coverage.coveragereport.cover',
...              '2 new untested lines')
z3c.coverage.coveragereport: 2 new untested lines
See http://example.com/coverage/z3c.coverage.coveragereport.html
<BLANKLINE>

Links to web pages

Report emailer can also include links to web pages with the coverage reports (e.g. the ones you can get from the coverage tool distributed with z3c.coverage).

>>> emailer = ReportEmailer('Some Bot <bot@example.com>',
...                         'Maintainer <m@example.com>',
...                         'Test coverage regressions',
...                         web_url='http://example.com/coverage',
...                         mailer=FakeMailSender())
>>> emailer.warn('/tmp/coverage/z3c.coverage.coveragediff.cover',
...              '3 new untested lines')
>>> emailer.warn('/tmp/coverage/z3c.coverage.coveragereport.cover',
...              '2 new untested lines')
>>> emailer.send()
From: Some Bot <bot@example.com>
To: Maintainer <m@example.com>
Subject: Test coverage regressions
---
z3c.coverage.coveragediff: 3 new untested lines
See http://example.com/coverage/z3c.coverage.coveragediff.html
<BLANKLINE>
z3c.coverage.coveragereport: 2 new untested lines
See http://example.com/coverage/z3c.coverage.coveragereport.html
<BLANKLINE>

Empty reports

Empty reports are not sent out.

>>> emailer = ReportEmailer('Some Bot <bot@example.com>',
...                         'Maintainer <m@example.com>',
...                         'Test coverage regressions',
...                         mailer=FakeMailSender())
>>> emailer.send()

Help message

>>> run(['coveragediff', '--help'])
Usage: coveragediff [options] olddir newdir
<BLANKLINE>
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 URL

Missing arguments

>>> run(['coveragediff'])
Usage: coveragediff [options] olddir newdir
<BLANKLINE>
coveragediff: error: wrong number of arguments
(returned exit code 2)

>>> run(['coveragediff', 'somedir'])
Usage: coveragediff [options] olddir newdir
<BLANKLINE>
coveragediff: error: wrong number of arguments
(returned exit code 2)

Excess arguments

>>> run(['coveragediff', 'dir1', 'dir2', 'dir3'])
Usage: coveragediff [options] olddir newdir
<BLANKLINE>
coveragediff: error: wrong number of arguments
(returned exit code 2)

Regular run

coveragediff follows the hallowed Unix tradition and does not print any unnecessary output, just the basics

>>> run(['coveragediff', sampleinput_dir, another_dir])
z3c.coverage.coveragediff: 36 new lines of untested code
z3c.coverage.fakenewmodule: new file with 3 lines of untested code (out of 13)

It means that if you have no coverage regressions in your test suite, the output will be empty

>>> run(['coveragediff', another_dir, another_dir])

Include/exclude patterns

>>> run(['coveragediff', sampleinput_dir, another_dir,
...      '--include', 'fake'])
z3c.coverage.fakenewmodule: new file with 3 lines of untested code (out of 13)

>>> run(['coveragediff', sampleinput_dir, another_dir,
...      '--exclude', 'fake'])
z3c.coverage.coveragediff: 36 new lines of untested code

Links to web pages

If you use coveragereport to produce HTML versions of the plain-text coverage files, and you have those available on the web, you can ask coveragediff to include links to the appropriate modules for convenient copy and paste (or clickety-clicking for those of us who use superior terminal emulators like GNOME Terminal).

>>> run(['coveragediff', sampleinput_dir, another_dir,
...      '--web-url', 'http://example.com/coverage'])
z3c.coverage.coveragediff: 36 new lines of untested code
See http://example.com/coverage/z3c.coverage.coveragediff.html
<BLANKLINE>
z3c.coverage.fakenewmodule: new file with 3 lines of untested code (out of 13)
See http://example.com/coverage/z3c.coverage.fakenewmodule.html
<BLANKLINE>

Reports via email

You can ask for the output to be emailed instead of being printed to stdout.

>>> MailSender.connection_class = FakeSMTP
>>> run(['coveragediff', sampleinput_dir, another_dir,
...      '--email', 'Project List <dev@example.com>',
...      '--from', 'Coverage Daemon <root@example.com>'])
Connecting to localhost:25
MAIL FROM:<root@example.com>
RCPT TO:<dev@example.com>
DATA
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: Coverage Daemon <root@example.com>
To: Project List <dev@example.com>
Subject: Unit test coverage regression
<BLANKLINE>
z3c.coverage.coveragediff: 36 new lines of untested code
z3c.coverage.fakenewmodule: new file with 3 lines of untested code (out of 13)
.
QUIT

coveragediff.py is a script

For convenience you can download the coveragediff.py module and run it as a script

>>> sys.argv = ['coveragediff', sampleinput_dir, another_dir]
>>> script_file = os.path.join(z3c.coverage.__path__[0], 'coveragediff.py')
>>> execfile(script_file, dict(__name__='__main__'))
z3c.coverage.coveragediff: 36 new lines of untested code
z3c.coverage.fakenewmodule: new file with 3 lines of untested code (out of 13)