Merge pull request #4927 from tkf/skip-doctest

Make pytest.skip work in doctest

Author: asottile

AUTHORS

@@ -222,6 +222,7 @@ Steffen Allner
 Stephan Obermann
 Sven-Hendrik Haase
 Tadek Teleżyński
+Takafumi Arakaki
 Tarcisio Fischer
 Tareq Alayan
 Ted Xiao

changelog/4911.feature.rst

@@ -0,0 +1 @@
+Doctests can be skipped now dynamically using ``pytest.skip()``.

src/_pytest/doctest.py

@@ -15,6 +15,7 @@
 from _pytest._code.code import TerminalRepr
 from _pytest.compat import safe_getattr
 from _pytest.fixtures import FixtureRequest
+from _pytest.outcomes import Skipped
 
 DOCTEST_REPORT_CHOICE_NONE = "none"
 DOCTEST_REPORT_CHOICE_CDIFF = "cdiff"
@@ -153,6 +154,8 @@ def report_failure(self, out, test, example, got):
                 raise failure
 
         def report_unexpected_exception(self, out, test, example, exc_info):
+            if isinstance(exc_info[1], Skipped):
+                raise exc_info[1]
             failure = doctest.UnexpectedException(test, example, exc_info)
             if self.continue_on_failure:
                 out.append(failure)

src/_pytest/outcomes.py

@@ -80,7 +80,8 @@ def skip(msg="", **kwargs):
     Skip an executing test with the given message.
 
     This function should be called only during testing (setup, call or teardown) or
-    during collection by using the ``allow_module_level`` flag.
+    during collection by using the ``allow_module_level`` flag.  This function can
+    be called in doctests as well.
 
     :kwarg bool allow_module_level: allows this function to be called at
         module level, skipping the rest of the module. Default to False.
@@ -89,6 +90,9 @@ def skip(msg="", **kwargs):
         It is better to use the :ref:`pytest.mark.skipif ref` marker when possible to declare a test to be
         skipped under certain conditions like mismatching platforms or
         dependencies.
+        Similarly, use the ``# doctest: +SKIP`` directive (see `doctest.SKIP
+        <https://docs.python.org/3/library/doctest.html#doctest.SKIP>`_)
+        to skip a doctest statically.
     """
     __tracebackhide__ = True
     allow_module_level = kwargs.pop("allow_module_level", False)

testing/test_doctest.py

@@ -188,6 +188,18 @@ def test_doctest_unexpected_exception(self, testdir):
             ]
         )
 
+    def test_doctest_skip(self, testdir):
+        testdir.maketxtfile(
+            """
+            >>> 1
+            1
+            >>> import pytest
+            >>> pytest.skip("")
+        """
+        )
+        result = testdir.runpytest("--doctest-modules")
+        result.stdout.fnmatch_lines(["*1 skipped*"])
+
     def test_docstring_partial_context_around_error(self, testdir):
         """Test that we show some context before the actual line of a failing
         doctest.