SVN: zope.testing/trunk/src/zope/testing/testrunner/find.py - make doctest for StartUpFailure more understandable

Log message for revision 89915:
  - make doctest for StartUpFailure more understandable
  - add test for StartUpFailure being returned when postmortem debugging is enabled by no traceback is supplied *sigh*

Changed:
  U   zope.testing/trunk/src/zope/testing/testrunner/find.py

-=-
Modified: zope.testing/trunk/src/zope/testing/testrunner/find.py
===================================================================
--- zope.testing/trunk/src/zope/testing/testrunner/find.py	2008-08-16 15:49:38 UTC (rev 89914)
+++ zope.testing/trunk/src/zope/testing/testrunner/find.py	2008-08-16 16:37:34 UTC (rev 89915)
@@ -35,28 +35,40 @@
     ...    post_mortem = False
     >>> options = Options()
     
-    Normally the StartUpFailure just acts as an emtpy test suite to satisfy
+    Normally the StartUpFailure just acts as an empty test suite to satisfy
     the test runner and statistics:
     
-    >>> StartUpFailure(options, None, None)
-    <StartUpFailure module=None>
+    >>> s = StartUpFailure(options, None, None)
+    >>> isinstance(s,unittest.TestCase)
+    True
 
-    The post mortem debugger needs real exception information:
+    However, if the post mortem option is enabled:
 
+    >>> options.post_mortem = True
+
+    ...then the the StartUpFailure will start the debugger and stop
+    the test run after the debugger quits.
+    
+    To simulate this, we need an exception and its associated
+    exc_info: 
+
     >>> import sys
     >>> try:
     ...    raise Exception()
     ... except:
     ...     exc_info = sys.exc_info()
 
-    If the post mortem option is enabled the StartUpFailure will start
-    the debugger and stop the test run after the debugger quits:
-
+    To simulate the user pressing 'c' and hitting return in the
+    debugger, we use a FakeInputContinueGenerator:
+    
     >>> from zope.testing.testrunner.runner import FakeInputContinueGenerator
     >>> old_stdin = sys.stdin
+    >>> sys.stdin = FakeInputContinueGenerator()
 
-    >>> options.post_mortem = True
-    >>> sys.stdin = FakeInputContinueGenerator()
+    Now we can see the EndRun exception that is raised by the
+    postmortem debugger to indicate that debugging is finished and the
+    test run should be terminated:
+    
     >>> try:
     ...     StartUpFailure(options, None, exc_info)
     ... finally:
@@ -64,10 +76,24 @@
     Traceback (most recent call last):
     EndRun
 
+    Annoyingly, sometimes StartupFailures occur when postmortem debugging
+    is enabled but no exc_info is passed. In this case, we raise a
+    sensible exception rather than letting the debugger barf with an
+    AttributeError:
+
+    >>> options.post_mortem = True
+    >>> StartUpFailure(options, None, exc_info[:2]+(None,))
+    Traceback (most recent call last):
+    ...
+    TypeError: If post_mortem is specified, full exc_info must be passed!
     """
 
     def __init__(self, options, module, exc_info):
         if options.post_mortem:
+            for item in exc_info:
+                if item is None:
+                    raise TypeError('If post_mortem is specified, '
+                                    'full exc_info must be passed!')
             zope.testing.testrunner.debug.post_mortem(exc_info)
         self.module = module
         self.exc_info = exc_info