Merge lp:~lifeless/testtools/discovery into lp:~testtools-committers/testtools/trunk

[Robert Collins]

Document and polish the test discovery feature.

Document and polish the test discovery feature.

[Jonathan Lange (jml)]

Hey Rob,

Thanks for the polish & documentation. It's nice to see the manual kept up-to-date, and I'm sure it helps our users a lot.

Could you please capitalize Python in the MANUAL, and put a space between Python and its version number before you land this?

Thanks,
jml

review: Approve

=== modified file 'MANUAL'
--- MANUAL	2010-06-11 00:51:36 +0000
+++ MANUAL	2010-06-13 22:22:22 +0000
@@ -213,3 +213,16 @@
 
 Testtools provides a convenient way to run a test suite using the testtools
 result object: python -m testtools.run testspec [testspec...].
+
+Test discovery
+--------------
+
+Testtools includes a backported version of the Python2.7 glue for using the
+discover test discovery module. If you either have python 2.7/3.1 or newer, or
+install the 'discover' module, then you can invoke discovery::
+
+    python -m testtools.run discover [path]
+
+For more information see the Python2.7 unittest documentation, or::
+
+    python -m testtools.run --help

=== modified file 'testtools/run.py'
--- testtools/run.py	2010-06-11 00:04:30 +0000
+++ testtools/run.py	2010-06-13 22:22:22 +0000
@@ -54,6 +54,10 @@
 #    it won't be on old python versions.
 #  - print calls have been been made single-source python3 compatibile.
 #  - exception handling likewise.
+#  - The default help has been changed to USAGE_AS_MAIN and USAGE_FROM_MODULE
+#    removed.
+#  - A tweak has been added to detect 'python -m testtools.run' and use a
+#    better progName in that case.
 
 FAILFAST     = "  -f, --failfast   Stop on first failure\n"
 CATCHBREAK   = "  -c, --catch      Catch control-C and display results\n"
@@ -88,28 +92,12 @@
 level directory of the project.
 """
 
-USAGE_FROM_MODULE = """\
-Usage: %(progName)s [options] [test] [...]
-
-Options:
-  -h, --help       Show this message
-  -v, --verbose    Verbose output
-  -q, --quiet      Minimal output
-%(failfast)s%(catchbreak)s%(buffer)s
-Examples:
-  %(progName)s                               - run default set of tests
-  %(progName)s MyTestSuite                   - run suite 'MyTestSuite'
-  %(progName)s MyTestCase.testSomething      - run MyTestCase.testSomething
-  %(progName)s MyTestCase                    - run all 'test*' test methods
-                                               in MyTestCase
-"""
-
 
 class TestProgram(object):
     """A command-line program that runs a set of tests; this is primarily
        for making test modules conveniently executable.
     """
-    USAGE = USAGE_FROM_MODULE
+    USAGE = USAGE_AS_MAIN
 
     # defaults for testing
     failfast = catchbreak = buffer = progName = None
@@ -135,7 +123,12 @@
         self.defaultTest = defaultTest
         self.testRunner = testRunner
         self.testLoader = testLoader
-        self.progName = os.path.basename(argv[0])
+        progName = argv[0]
+        if progName.endswith('testtools%srun.py' % os.path.sep):
+            progName = 'testtools.run'
+        else:
+            progName = os.path.basename(argv[0])
+        self.progName = progName
         self.parseArgs(argv)
         self.runTests()