bpo-37094: Add example for TestCase.skipTest in unittest doc (GH-13645)

Also includes other minor test skipping doc improvements.

https://bugs.python.org/issue37094

diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 8ad2abd3d89a44a5fb092d48f0205d842c49dc6f..54a9f2c6f7355e7205578f1b5a81839780a84230 100644 (file)
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -510,7 +510,8 @@ that is broken and will fail, but shouldn't be counted as a failure on a
 :class:`TestResult`.
 
 Skipping a test is simply a matter of using the :func:`skip` :term:`decorator`
-or one of its conditional variants.
+or one of its conditional variants, calling :meth:`TestCase.skipTest` within a
+:meth:`~TestCase.setUp` or test method, or raising :exc:`SkipTest` directly.
 
 Basic skipping looks like this::
 
@@ -531,16 +532,23 @@ Basic skipping looks like this::
            # windows specific testing code
            pass
 
+       def test_maybe_skipped(self):
+           if not external_resource_available():
+               self.skipTest("external resource not available")
+           # test code that depends on the external resource
+           pass
+
 This is the output of running the example above in verbose mode::
 
    test_format (__main__.MyTestCase) ... skipped 'not supported in this library version'
    test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping'
+   test_maybe_skipped (__main__.MyTestCase) ... skipped 'external resource not available'
    test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'
 
    ----------------------------------------------------------------------
-   Ran 3 tests in 0.005s
+   Ran 4 tests in 0.005s
 
-   OK (skipped=3)
+   OK (skipped=4)
 
 Classes can be skipped just like methods::
 
@@ -568,7 +576,7 @@ the test unless the passed object has a certain attribute::
            return lambda func: func
        return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))
 
-The following decorators implement test skipping and expected failures:
+The following decorators and exception implement test skipping and expected failures:
 
 .. decorator:: skip(reason)