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

[Miss Islington (bot)]

https://github.com/python/cpython/commit/ffed76b6fc4d7dd0244b662d6e5738eb496d9def
commit: ffed76b6fc4d7dd0244b662d6e5738eb496d9def
branch: master
author: Makdon <makdon at makdon.me>
committer: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
date: 2019-05-31T09:19:11-07:00
summary:

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

files:
M Doc/library/unittest.rst

diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 8ad2abd3d89a..54a9f2c6f735 100644
--- 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)