#16522: Add FAIL_FAST flag to doctest.

Patch by me, most of the work (doc and tests) by Daniel Urban.

Doc/library/doctest.rst

@@ -633,6 +633,16 @@ The second group of options controls how test failures are reported:
    the output is suppressed.
 
 
+.. data:: FAIL_FAST
+
+   When specified, exit after the first failing example and don't attempt to run
+   the remaining examples. Thus, the number of failures reported will always be 1.
+   This flag may be useful during debugging, since examples after the first
+   failure won't even produce debugging output.
+
+   .. versionadded:: 3.4
+
+
 .. data:: REPORTING_FLAGS
 
    A bitmask or'ing together all the reporting flags above.

Doc/whatsnew/3.4.rst

@@ -150,7 +150,11 @@ New Modules
 Improved Modules
 ================
 
-* None yet.
+doctest
+-------
+
+Added ``FAIL_FAST`` flag to halt test running as soon as the first failure is
+detected.  (Contributed by R. David Murray and Daniel Urban in :issue:`16522`.)
 
 
 Optimizations

Lib/doctest.py

@@ -62,6 +62,7 @@ def _test():
     'REPORT_NDIFF',
     'REPORT_ONLY_FIRST_FAILURE',
     'REPORTING_FLAGS',
+    'FAIL_FAST',
     # 1. Utility Functions
     # 2. Example & DocTest
     'Example',
@@ -150,11 +151,13 @@ def register_optionflag(name):
 REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
 REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
 REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
+FAIL_FAST = register_optionflag('FAIL_FAST')
 
 REPORTING_FLAGS = (REPORT_UDIFF |
                    REPORT_CDIFF |
                    REPORT_NDIFF |
-                   REPORT_ONLY_FIRST_FAILURE)
+                   REPORT_ONLY_FIRST_FAILURE |
+                   FAIL_FAST)
 
 # Special string markers for use in `want` strings:
 BLANKLINE_MARKER = '<BLANKLINE>'
@@ -1342,6 +1345,9 @@ def __run(self, test, compileflags, out):
             else:
                 assert False, ("unknown outcome", outcome)
 
+            if failures and self.optionflags & FAIL_FAST:
+                break
+
         # Restore the option flags (in case they were modified)
         self.optionflags = original_optionflags
 

Lib/test/test_doctest.py

@@ -1409,8 +1409,40 @@ def optionflags(): r"""
         2
     TestResults(failed=3, attempted=5)
 
-For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
-count as failures:
+The FAIL_FAST flag causes the runner to exit after the first failing example,
+so subsequent examples are not even attempted:
+
+    >>> flags = doctest.FAIL_FAST
+    >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
+    ... # doctest: +ELLIPSIS
+    **********************************************************************
+    File ..., line 5, in f
+    Failed example:
+        print(2) # first failure
+    Expected:
+        200
+    Got:
+        2
+    TestResults(failed=1, attempted=2)
+
+Specifying both FAIL_FAST and REPORT_ONLY_FIRST_FAILURE is equivalent to
+FAIL_FAST only:
+
+    >>> flags = doctest.FAIL_FAST | doctest.REPORT_ONLY_FIRST_FAILURE
+    >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
+    ... # doctest: +ELLIPSIS
+    **********************************************************************
+    File ..., line 5, in f
+    Failed example:
+        print(2) # first failure
+    Expected:
+        200
+    Got:
+        2
+    TestResults(failed=1, attempted=2)
+
+For the purposes of both REPORT_ONLY_FIRST_FAILURE and FAIL_FAST, unexpected
+exceptions count as failures:
 
     >>> def f(x):
     ...     r'''
@@ -1437,6 +1469,17 @@ def optionflags(): r"""
         ...
         ValueError: 2
     TestResults(failed=3, attempted=5)
+    >>> flags = doctest.FAIL_FAST
+    >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
+    ... # doctest: +ELLIPSIS
+    **********************************************************************
+    File ..., line 5, in f
+    Failed example:
+        raise ValueError(2) # first failure
+    Exception raised:
+        ...
+        ValueError: 2
+    TestResults(failed=1, attempted=2)
 
 New option flags can also be registered, via register_optionflag().  Here
 we reach into doctest's internals a bit.

Misc/NEWS

@@ -138,6 +138,8 @@ Core and Builtins
 Library
 -------
 
+- Issue #16522: added FAIL_FAST flag to doctest.
+
 - Issue #15627: Add the importlib.abc.SourceLoader.compile_source() method.
 
 - Issue #16408: Fix file descriptors not being closed in error conditions