[Checkins] SVN: z3c.coverage/trunk/src/z3c/coverage/coveragediff.txt Test most of main().

[Marius Gedminas]

Log message for revision 78195:
  Test most of main().
  
  

Changed:
  U   z3c.coverage/trunk/src/z3c/coverage/coveragediff.txt

-=-
Modified: z3c.coverage/trunk/src/z3c/coverage/coveragediff.txt
===================================================================
--- z3c.coverage/trunk/src/z3c/coverage/coveragediff.txt	2007-07-19 20:52:13 UTC (rev 78194)
+++ z3c.coverage/trunk/src/z3c/coverage/coveragediff.txt	2007-07-19 20:59:21 UTC (rev 78195)
@@ -1,5 +1,5 @@
-coveragediff
-============
+coveragediff internals
+======================
 
 ``coveragediff`` is a tool that can be used to compare two directories with
 coverage reports.  It reports regressions, that is, increases in the number
@@ -27,7 +27,7 @@
     z3c.coverage.tests.cover
 
 The function ``filter_coverage_files`` looks for plain-text coverage reports
- in a given location that match a set of include and exclude patterns
+in a given location that match a set of include and exclude patterns
 
     >>> from z3c.coverage.coveragediff import filter_coverage_files
     >>> for filename in sorted(filter_coverage_files(sampleinput_dir)):
@@ -174,6 +174,14 @@
     QUIT
 
 
+Small utilities
+---------------
+
+There are several small utility functions like ``strip``, ``urljoin``,
+``matches`` and ``filter_files``.  These are described (and tested) adequately
+by their doctests.
+
+
 ReportPrinter
 -------------
 
@@ -289,3 +297,117 @@
     ...                         mailer=FakeMailSender())
     >>> emailer.send()
 
+
+Main function
+-------------
+
+A traditional ``main`` function parses command-line arguments and hooks up
+``compare_dirs`` with the appropriate reporter.
+
+    >>> import sys
+    >>> from z3c.coverage.coveragediff import main
+
+    >>> def run(args):
+    ...     try:
+    ...         old_stderr = sys.stderr
+    ...         sys.argv = args
+    ...         sys.stderr = sys.stdout
+    ...         try:
+    ...             main()
+    ...         finally:
+    ...             sys.stderr = old_stderr
+    ...     except SystemExit, e:
+    ...         if e.code:
+    ...             print "(returned exit code %s)" % e.code
+
+
+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>
+