re-arrange "py.test -h" command line option grouping and update some plugin docs.

--HG--
branch : trunk

bin-for-dist/makepluginlist.py

@@ -7,9 +7,9 @@ plugins = [
             'skipping mark pdb figleaf coverage '
             'monkeypatch capture recwarn tmpdir',),
     ('testing domains', 
-            'oejskit django'),
+            'oejskit django genscript'),
     ('reporting and failure logging', 
-            'pastebin xmlresult resultlog terminal',),
+            'pastebin logxml xmlresult resultlog terminal',),
     ('other testing conventions',
             'unittest nose doctest restdoc'),
     ('core debugging / help functionality', 

doc/test/plugin/capture.txt

@@ -116,7 +116,7 @@ command line options
 
 
 ``--capture=method``
-    set capturing method during tests: fd (default)|sys|no.
+    per-test capturing method: one of fd (default)|sys|no.
 ``-s``
     shortcut for --capture=no.
 

doc/test/plugin/figleaf.txt

@@ -2,12 +2,12 @@
 pytest_figleaf plugin
 =====================
 
-write and report coverage data with 'figleaf'.
+report python test coverage using the 'figleaf' package.
 
 .. contents::
   :local:
 
-
+Not enabled by default (use "-p" or conftest settings to do so).
 
 command line options
 --------------------
@@ -18,7 +18,7 @@ command line options
 ``--fig-data=dir``
     set tracing file, default: ".figleaf".
 ``--fig-html=dir``
-    set html reporting dir, default "html").
+    set html reporting dir, default "html".
 
 Start improving this plugin in 30 seconds
 =========================================

doc/test/plugin/helpconfig.txt

@@ -13,10 +13,12 @@ command line options
 --------------------
 
 
-``--help-config``
-    show available conftest.py and ENV-variable names.
 ``--version``
     display py lib version and import information.
+``-p name``
+    early-load given plugin (multi-allowed).
+``--help-config``
+    show available conftest.py and ENV-variable names.
 
 Start improving this plugin in 30 seconds
 =========================================

doc/test/plugin/index.txt

@@ -8,7 +8,7 @@ mark_ generic mechanism for marking python functions.
 
 pdb_ interactive debugging with the Python Debugger.
 
-figleaf_ write and report coverage data with 'figleaf'.
+figleaf_ report python test coverage using the 'figleaf' package.
 
 coverage_ (3rd) for testing with Ned's coverage module 
 
@@ -28,15 +28,19 @@ oejskit_ (3rd) run javascript tests in real life browsers
 
 django_ (3rd) for testing django applications
 
+genscript_ generate standalone test script to be distributed along with an application.
+
 
 reporting and failure logging
 =============================
 
 pastebin_ submit failure or test session information to a pastebin service.
 
+logxml_ logging of test results in JUnit-XML format, for use with Hudson
+
 xmlresult_ (3rd) for generating xml reports and CruiseControl integration
 
-resultlog_ resultlog plugin for machine-readable logging of test results.
+resultlog_ non-xml machine-readable logging of test results.
 
 terminal_ Implements terminal reporting of the full testing process.
 

doc/test/plugin/links.txt

@@ -1,42 +1,46 @@
-.. _`helpconfig`: helpconfig.html
+.. _`pytest_logxml.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_logxml.py
 .. _`terminal`: terminal.html
-.. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_recwarn.py
+.. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_recwarn.py
 .. _`unittest`: unittest.html
-.. _`pytest_monkeypatch.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_monkeypatch.py
+.. _`pytest_monkeypatch.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_monkeypatch.py
+.. _`pytest_genscript.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_genscript.py
 .. _`pastebin`: pastebin.html
 .. _`skipping`: skipping.html
+.. _`genscript`: genscript.html
 .. _`plugins`: index.html
 .. _`mark`: mark.html
 .. _`tmpdir`: tmpdir.html
-.. _`pytest_doctest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_doctest.py
+.. _`pytest_doctest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_doctest.py
 .. _`capture`: capture.html
-.. _`pytest_nose.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_nose.py
-.. _`pytest_restdoc.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_restdoc.py
+.. _`pytest_nose.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_nose.py
+.. _`pytest_restdoc.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_restdoc.py
 .. _`restdoc`: restdoc.html
-.. _`pytest_pastebin.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_pastebin.py
-.. _`pytest_tmpdir.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_tmpdir.py
-.. _`pytest_figleaf.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_figleaf.py
-.. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_hooklog.py
-.. _`pytest_skipping.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_skipping.py
+.. _`pytest_pastebin.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_pastebin.py
+.. _`pytest_tmpdir.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_tmpdir.py
+.. _`pytest_figleaf.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_figleaf.py
+.. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_hooklog.py
+.. _`logxml`: logxml.html
+.. _`helpconfig`: helpconfig.html
+.. _`pytest_skipping.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_skipping.py
 .. _`checkout the py.test development version`: ../../install.html#checkout
-.. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_helpconfig.py
+.. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_helpconfig.py
 .. _`oejskit`: oejskit.html
 .. _`doctest`: doctest.html
-.. _`pytest_mark.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_mark.py
+.. _`pytest_mark.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_mark.py
 .. _`get in contact`: ../../contact.html
-.. _`pytest_capture.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_capture.py
+.. _`pytest_capture.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_capture.py
 .. _`figleaf`: figleaf.html
 .. _`customize`: ../customize.html
 .. _`hooklog`: hooklog.html
-.. _`pytest_terminal.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_terminal.py
+.. _`pytest_terminal.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_terminal.py
 .. _`recwarn`: recwarn.html
-.. _`pytest_pdb.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_pdb.py
+.. _`pytest_pdb.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_pdb.py
 .. _`monkeypatch`: monkeypatch.html
 .. _`coverage`: coverage.html
 .. _`resultlog`: resultlog.html
 .. _`django`: django.html
 .. _`xmlresult`: xmlresult.html
-.. _`pytest_unittest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_unittest.py
+.. _`pytest_unittest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_unittest.py
 .. _`nose`: nose.html
-.. _`pytest_resultlog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.1.1post1/py/plugin/pytest_resultlog.py
+.. _`pytest_resultlog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.2.0a1/py/plugin/pytest_resultlog.py
 .. _`pdb`: pdb.html

doc/test/plugin/pdb.txt

@@ -14,7 +14,7 @@ command line options
 
 
 ``--pdb``
-    start pdb (the Python debugger) on errors.
+    start the interactive Python debugger on errors.
 
 Start improving this plugin in 30 seconds
 =========================================

doc/test/plugin/resultlog.txt

@@ -2,12 +2,15 @@
 pytest_resultlog plugin
 =======================
 
-resultlog plugin for machine-readable logging of test results.
+non-xml machine-readable logging of test results.
 
 .. contents::
   :local:
 
-Useful for buildbot integration code.
+Useful for buildbot integration code.  See the `PyPy-test`_ 
+   web page for post-processing. 
+
+.. _`PyPy-test`: http://codespeak.net:8099/summary
 
 command line options
 --------------------

doc/test/plugin/terminal.txt

@@ -18,13 +18,11 @@ command line options
 ``-l, --showlocals``
     show locals in tracebacks (disabled by default).
 ``--report=opts``
-    comma separated options, valid: skipped,xfailed
+    show more info, valid: skipped,xfailed
 ``--tb=style``
     traceback verboseness (long/short/no).
 ``--fulltrace``
     don't cut any tracebacks (default is to cut).
-``--collectonly``
-    only collect tests, don't execute them.
 ``--traceconfig``
     trace considerations of conftest.py files.
 ``--nomagic``

py/impl/code/_assertionnew.py

@@ -52,7 +52,7 @@ def interpret(source, frame, should_fail=False):
     if should_fail:
         return ("(assertion failed, but when it was re-run for "
                 "printing intermediate values, it did not fail.  Suggestions: "
-                "compute assert expression before the assert or use --nomagic)")
+                "compute assert expression before the assert or use --no-assert)")
 
 def run(offending_line, frame=None):
     if frame is None:

py/plugin/pytest_capture.py

@@ -91,7 +91,7 @@ def pytest_addoption(parser):
     group = parser.getgroup("general")
     group._addoption('--capture', action="store", default=None,
         metavar="method", type="choice", choices=['fd', 'sys', 'no'],
-        help="set capturing method during tests: fd (default)|sys|no.")
+        help="per-test capturing method: one of fd (default)|sys|no.")
     group._addoption('-s', action="store_const", const="no", dest="capture", 
         help="shortcut for --capture=no.")
 

py/plugin/pytest_default.py

@@ -55,28 +55,31 @@ def pytest_addoption(parser):
     group._addoption('-x', '--exitfirst',
                action="store_true", dest="exitfirst", default=False,
                help="exit instantly on first error or failed test."),
-    group.addoption("--ignore", action="append", metavar="path", 
-        help="ignore path during collection (multi-allowed).")
     group._addoption('-k',
         action="store", dest="keyword", default='',
         help="only run test items matching the given "
              "space separated keywords.  precede a keyword with '-' to negate. "
              "Terminate the expression with ':' to treat a match as a signal "
              "to run all subsequent tests. ")
-    group._addoption('-p', action="append", dest="plugins", default = [],
-               help=("load the specified plugin after command line parsing. "))
     if execnet:
         group._addoption('-f', '--looponfail',
                    action="store_true", dest="looponfail", default=False,
                    help="run tests, re-run failing test set until all pass.")
 
+    group = parser.getgroup("collect", "collection")
+    group.addoption('--collectonly',
+        action="store_true", dest="collectonly",
+        help="only collect tests, don't execute them."),
+    group.addoption("--ignore", action="append", metavar="path", 
+        help="ignore path during collection (multi-allowed).")
+    group.addoption('--confcutdir', dest="confcutdir", default=None, 
+        metavar="dir",
+        help="only load conftest.py's relative to specified dir.")
+
     group = parser.getgroup("debugconfig", 
         "test process debugging and configuration")
     group.addoption('--basetemp', dest="basetemp", default=None, metavar="dir",
                help="base temporary directory for this test run.")
-    group.addoption('--confcutdir', dest="confcutdir", default=None, 
-        metavar="dir",
-        help="only load conftest.py's relative to specified dir.")
     if execnet:
         add_dist_options(parser)
     else:

py/plugin/pytest_doctest.py

@@ -27,7 +27,7 @@ from py.impl.code.code import TerminalRepr, ReprFileLocation
 import doctest
 
 def pytest_addoption(parser):
-    group = parser.getgroup("general")
+    group = parser.getgroup("collect")
     group.addoption("--doctest-modules", 
         action="store_true", default=False, 
         help="run doctests in all .py modules",

py/plugin/pytest_figleaf.py

@@ -1,6 +1,7 @@
 """
-write and report coverage data with 'figleaf'. 
+report python test coverage using the 'figleaf' package.
 
+Not enabled by default (use "-p" or conftest settings to do so). 
 """
 import py
 py.test.importorskip("figleaf")

py/plugin/pytest_genscript.py

@@ -1,4 +1,7 @@
 #! /usr/bin/env python
+"""
+generate standalone test script to be distributed along with an application. 
+"""
 
 import os
 import zlib
@@ -10,7 +13,7 @@ except Importerror:
     import cPickle as pickle
 
 def pytest_addoption(parser):
-    group = parser.getgroup("general")
+    group = parser.getgroup("debugconfig")
     group.addoption("--genscript", action="store", default=None, 
         dest="genscript", metavar="path", 
         help="create standalone py.test script at given target path.")

py/plugin/pytest_helpconfig.py

@@ -5,10 +5,13 @@ import inspect, sys
 
 def pytest_addoption(parser):
     group = parser.getgroup('debugconfig')
-    group.addoption("--help-config", action="store_true", dest="helpconfig", 
-            help="show available conftest.py and ENV-variable names.")
     group.addoption('--version', action="store_true", 
             help="display py lib version and import information.")
+    group._addoption('-p', action="append", dest="plugins", default = [],
+               metavar="name", 
+               help="early-load given plugin (multi-allowed).")
+    group.addoption("--help-config", action="store_true", dest="helpconfig", 
+            help="show available conftest.py and ENV-variable names.")
 
 def pytest_configure(__multicall__, config):
     if config.option.version:

py/plugin/pytest_logxml.py

@@ -1,13 +1,13 @@
 """
-   logxml plugin for machine-readable logging of test results. 
-   Based on initial code from Ross Lawley.
+   logging of test results in JUnit-XML format, for use with Hudson 
+   and build integration servers.  Based on initial code from Ross Lawley.
 """
 
 import py
 import time
 
 def pytest_addoption(parser):
-    group = parser.getgroup("general")
+    group = parser.getgroup("terminal reporting")
     group.addoption('--xml', action="store", dest="xmlpath", 
            metavar="path", default=None,
            help="create junit-xml style report file at the given path.")

py/plugin/pytest_pastebin.py

@@ -27,7 +27,7 @@ class url:
     show = base + "/show/"
 
 def pytest_addoption(parser):
-    group = parser.getgroup("general")
+    group = parser.getgroup("terminal reporting")
     group._addoption('--pastebin', metavar="mode",
         action='store', dest="pastebin", default=None, 
         type="choice", choices=['failed', 'all'], 

py/plugin/pytest_pdb.py

@@ -13,7 +13,7 @@ def pytest_addoption(parser):
     group = parser.getgroup("general") 
     group._addoption('--pdb',
                action="store_true", dest="usepdb", default=False,
-               help="start pdb (the Python debugger) on errors.")
+               help="start the interactive Python debugger on errors.")
 
 
 def pytest_configure(__multicall__, config):

py/plugin/pytest_resultlog.py

@@ -1,5 +1,9 @@
-"""resultlog plugin for machine-readable logging of test results. 
-   Useful for buildbot integration code. 
+"""non-xml machine-readable logging of test results. 
+   Useful for buildbot integration code.  See the `PyPy-test`_ 
+   web page for post-processing. 
+
+.. _`PyPy-test`: http://codespeak.net:8099/summary
+ 
 """ 
 
 import py

py/plugin/pytest_runner.py

@@ -12,7 +12,7 @@ def pytest_addoption(parser):
     group = parser.getgroup("general") 
     group.addoption('--boxed',
                action="store_true", dest="boxed", default=False,
-               help="box each test run in a separate process") 
+               help="box each test run in a separate process (unix)") 
 
 # XXX move to pytest_sessionstart and fix py.test owns tests 
 def pytest_configure(config):

py/plugin/pytest_terminal.py

@@ -7,7 +7,7 @@ import py
 import sys
 
 def pytest_addoption(parser):
-    group = parser.getgroup("terminal reporting", after="general")
+    group = parser.getgroup("terminal reporting", "reporting", after="general")
     group._addoption('-v', '--verbose', action="count", 
                dest="verbose", default=0, help="increase verbosity."),
     group._addoption('-l', '--showlocals',
@@ -15,7 +15,7 @@ def pytest_addoption(parser):
                help="show locals in tracebacks (disabled by default).")
     group.addoption('--report',
                action="store", dest="report", default=None, metavar="opts",
-               help="comma separated options, valid: skipped,xfailed")
+               help="show more info, valid: skipped,xfailed")
     group._addoption('--tb', metavar="style", 
                action="store", dest="tbstyle", default='long',
                type="choice", choices=['long', 'short', 'no'],
@@ -25,9 +25,6 @@ def pytest_addoption(parser):
                help="don't cut any tracebacks (default is to cut).")
 
     group = parser.getgroup("debugconfig")
-    group.addoption('--collectonly',
-        action="store_true", dest="collectonly",
-        help="only collect tests, don't execute them."),
     group.addoption('--traceconfig',
                action="store_true", dest="traceconfig", default=False,
                help="trace considerations of conftest.py files."),