Make DocTestCase report as skipped if all examples in the doctest are…

… skipped
serhiy-storchaka · Mar 28, 2024 · Mar 27, 2024 · Mar 27, 2024 · Mar 27, 2024 · Mar 27, 2024
commit 4c7e74a13d39141497e77c3f23fcc56c74070700
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
@@ -1021,7 +1021,8 @@ from text files and modules with doctests:
    and runs the interactive examples in each file.  If an example in any file
    fails, then the synthesized unit test fails, and a :exc:`failureException`
    exception is raised showing the name of the file containing the test and a
-   (sometimes approximate) line number.
+   (sometimes approximate) line number.  If all the examples in a file are
+   skipped, then the synthesized unit test is also marked as skipped.
 
    Pass one or more paths (as strings) to text files to be examined.
 
@@ -1087,7 +1088,8 @@ from text files and modules with doctests:
    and runs each doctest in the module.  If any of the doctests fail, then the
    synthesized unit test fails, and a :exc:`failureException` exception is raised
    showing the name of the file containing the test and a (sometimes approximate)
-   line number.
+   line number.  If all the examples in a docstring are skipped, then the
+   synthesized unit test is also marked as skipped.
 
    Optional argument *module* provides the module to be tested.  It can be a module
    object or a (possibly dotted) module name.  If not specified, the module calling

diff --git a/Lib/doctest.py b/Lib/doctest.py
@@ -2262,12 +2262,13 @@ def runTest(self):
 
         try:
             runner.DIVIDER = "-"*70
-            failures, tries = runner.run(
-                test, out=new.write, clear_globs=False)
+            results = runner.run(test, out=new.write, clear_globs=False)
+            if results.skipped == results.attempted:
+                raise unittest.SkipTest(f"all examples were skipped")
         finally:
             sys.stdout = old
 
-        if failures:
+        if results.failed:
             raise self.failureException(self.format_failure(new.getvalue()))
 
     def format_failure(self, err):

diff --git a/Lib/test/test_doctest/sample_doctest_skip.py b/Lib/test/test_doctest/sample_doctest_skip.py
@@ -0,0 +1,37 @@
+"""This is a sample module used for testing doctest.
+
+This module includes various scenarios involving skips.
+"""
+
+# This test will pass.
+def no_skip():
+    """
+    >>> 2 + 2
+    4
+    """
+
+def single_skip():
+    """
+    >>> 2 + 2  # doctest: +SKIP
+    4
+    """
+
+def double_skip():
+    """
+    >>> 2 + 2  # doctest: +SKIP
+    4
+    >>> 3 + 3  # doctest: +SKIP
+    6
+    """
+
+# This test will fail.
+def partial_skip():
+    """
+    >>> 2 + 2  # doctest: +SKIP
+    4
+    >>> 2 + 2
+    5
+    """
+
+def no_examples():
+    """A docstring with no examples should not be counted as a skip."""
diff --git a/Lib/test/test_doctest/test_doctest.py b/Lib/test/test_doctest/test_doctest.py
@@ -2247,6 +2247,16 @@ def test_DocTestSuite():
          >>> suite.run(unittest.TestResult())
          <unittest.result.TestResult run=0 errors=0 failures=0>
 
+       If all examples in a docstring are skipped, unittest will report it as a
+       skipped test:
+
+         >>> suite = doctest.DocTestSuite('test.test_doctest.sample_doctest_skip')
+         >>> result = suite.run(unittest.TestResult())
+         >>> result
+         <unittest.result.TestResult run=4 errors=0 failures=1>
+        >>> len(result.skipped)
+        2
+
        We can use the current module:
 
          >>> suite = test.test_doctest.sample_doctest.test_suite()
@@ -2418,6 +2428,18 @@ def test_DocFileSuite():
          Traceback (most recent call last):
          ValueError: Package may only be specified for module-relative paths.
 
+       If all examples in a file are skipped, unittest will report it as a
+       skipped test:
+
+         >>> suite = doctest.DocFileSuite('test_doctest.txt',
+         ...                              'test_doctest4.txt',
+         ...                              'test_doctest_skip.txt')
+         >>> result = suite.run(unittest.TestResult())
+         >>> result
+         <unittest.result.TestResult run=3 errors=0 failures=1>
+        >>> len(result.skipped)
+        1
+
        You can specify initial global variables:
 
          >>> suite = doctest.DocFileSuite('test_doctest.txt',

diff --git a/Lib/test/test_doctest/test_doctest_skip.txt b/Lib/test/test_doctest/test_doctest_skip.txt
@@ -0,0 +1,4 @@
+This is a sample doctest in a text file, in which all examples are skipped.
+
+  >>> 2 + 2  # doctest: +SKIP
+  5
diff --git a/Misc/NEWS.d/next/Library/2024-03-27-16-43-42.gh-issue-117294.wbXNFv.rst b/Misc/NEWS.d/next/Library/2024-03-27-16-43-42.gh-issue-117294.wbXNFv.rst
@@ -0,0 +1,2 @@
+A ``DocTestCase`` now reports as skipped if all examples in the doctest are
+skipped.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@
		This is a sample doctest in a text file, in which all examples are skipped.

		>>> 2 + 2 # doctest: +SKIP
		5
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		A ``DocTestCase`` now reports as skipped if all examples in the doctest are
		skipped.