Make doctest SKIP option register doctests as SKIPPED rather than PASSED

Fix 957

CHANGELOG

@@ -159,6 +159,10 @@
 - fix issue890: changed extension of all documentation files from ``txt`` to
   ``rst``. Thanks to Abhijeet for the PR.
 
+- fix issue957: "# doctest: SKIP" option will now register doctests as SKIPPED
+  rather than PASSED.
+  Thanks Thomas Grainger for the report and Bruno Oliveira for the PR.
+
 - issue951: add new record_xml_property fixture, that supports logging
   additional information on xml output. Thanks David Diaz for the PR.
 

_pytest/doctest.py

@@ -47,6 +47,7 @@ class DoctestItem(pytest.Item):
         self.dtest = dtest
 
     def runtest(self):
+        _check_all_skipped(self.dtest)
         self.runner.run(self.dtest)
 
     def repr_failure(self, excinfo):
@@ -133,9 +134,20 @@ class DoctestTextfile(DoctestItem, pytest.File):
 
         parser = doctest.DocTestParser()
         test = parser.get_doctest(text, globs, name, filename, 0)
+        _check_all_skipped(test)
         runner.run(test)
 
 
+def _check_all_skipped(test):
+    """raises pytest.skip() if all examples in the given DocTest have the SKIP
+    option set.
+    """
+    import doctest
+    all_skipped = all(x.options.get(doctest.SKIP, False) for x in test.examples)
+    if all_skipped:
+        pytest.skip('all tests skipped by +SKIP option')
+
+
 class DoctestModule(pytest.File):
     def collect(self):
         import doctest

testing/test_doctest.py

@@ -446,3 +446,50 @@ class TestDoctests:
         reprec.assertoutcome(passed=passed, failed=int(not passed))
 
 
+class TestDocTestSkips:
+    """
+    If all examples in a doctest are skipped due to the SKIP option, then
+    the tests should be SKIPPED rather than PASSED. (#957)
+    """
+
+    @pytest.fixture(params=['text', 'module'])
+    def makedoctest(self, testdir, request):
+        def makeit(doctest):
+            mode = request.param
+            if mode == 'text':
+                testdir.maketxtfile(doctest)
+            else:
+                assert mode == 'module'
+                testdir.makepyfile('"""\n%s"""' % doctest)
+
+        return makeit
+
+    def test_one_skipped(self, testdir, makedoctest):
+        makedoctest("""
+            >>> 1 + 1  # doctest: +SKIP
+            2
+            >>> 2 + 2
+            4
+        """)
+        reprec = testdir.inline_run("--doctest-modules")
+        reprec.assertoutcome(passed=1)
+
+    def test_one_skipped_failed(self, testdir, makedoctest):
+        makedoctest("""
+            >>> 1 + 1  # doctest: +SKIP
+            2
+            >>> 2 + 2
+            200
+        """)
+        reprec = testdir.inline_run("--doctest-modules")
+        reprec.assertoutcome(failed=1)
+
+    def test_all_skipped(self, testdir, makedoctest):
+        makedoctest("""
+            >>> 1 + 1  # doctest: +SKIP
+            2
+            >>> 2 + 2  # doctest: +SKIP
+            200
+        """)
+        reprec = testdir.inline_run("--doctest-modules")
+        reprec.assertoutcome(skipped=1)