Refresh the documentation for the test.test_support module.

Doc/library/test.rst

@@ -131,13 +131,13 @@ guidelines to be followed:
              self.func(self.arg)
 
      class AcceptLists(TestFuncAcceptsSequences):
-         arg = [1,2,3]
+         arg = [1, 2, 3]
 
      class AcceptStrings(TestFuncAcceptsSequences):
          arg = 'abc'
 
      class AcceptTuples(TestFuncAcceptsSequences):
-         arg = (1,2,3)
+         arg = (1, 2, 3)
 
 
 .. seealso::
@@ -207,16 +207,9 @@ This module defines the following exceptions:
    methods.
 
 
-.. exception:: TestSkipped
-
-   Subclass of :exc:`TestFailed`. Raised when a test is skipped. This occurs when a
-   needed resource (such as a network connection) is not available at the time of
-   testing.
-
-
 .. exception:: ResourceDenied
 
-   Subclass of :exc:`TestSkipped`. Raised when a resource (such as a network
+   Subclass of :exc:`unittest.SkipTest`. Raised when a resource (such as a network
    connection) is not available. Raised by the :func:`requires` function.
 
 The :mod:`test.test_support` module defines the following constants:
@@ -241,7 +234,7 @@ The :mod:`test.test_support` module defines the following constants:
 
 .. data:: TESTFN
 
-   Set to the path that a temporary file may be created at. Any temporary that is
+   Set to the name that a temporary file could use. Any temporary file that is
    created should be closed and unlinked (removed).
 
 The :mod:`test.test_support` module defines the following functions:
@@ -249,21 +242,21 @@ The :mod:`test.test_support` module defines the following functions:
 
 .. function:: forget(module_name)
 
-   Removes the module named *module_name* from ``sys.modules`` and deletes any
+   Remove the module named *module_name* from ``sys.modules`` and deletes any
    byte-compiled files of the module.
 
 
 .. function:: is_resource_enabled(resource)
 
-   Returns :const:`True` if *resource* is enabled and available. The list of
+   Return :const:`True` if *resource* is enabled and available. The list of
    available resources is only set when :mod:`test.regrtest` is executing the
    tests.
 
 
 .. function:: requires(resource[, msg])
 
-   Raises :exc:`ResourceDenied` if *resource* is not available. *msg* is the
-   argument to :exc:`ResourceDenied` if it is raised. Always returns true if called
+   Raise :exc:`ResourceDenied` if *resource* is not available. *msg* is the
+   argument to :exc:`ResourceDenied` if it is raised. Always returns True if called
    by a function whose ``__name__`` is ``'__main__'``. Used when tests are executed
    by :mod:`test.regrtest`.
 
@@ -291,14 +284,24 @@ The :mod:`test.test_support` module defines the following functions:
    This will run all tests defined in the named module.
 
 
-.. function:: check_warnings()
+.. function:: check_warnings(*filters, quiet=False)
 
    A convenience wrapper for ``warnings.catch_warnings()`` that makes
    it easier to test that a warning was correctly raised with a single
    assertion. It is approximately equivalent to calling
    ``warnings.catch_warnings(record=True)``.
 
-   The main difference is that on entry to the context manager, a
+   It accepts 2-tuples ``("message regexp", WarningCategory)`` as positional
+   arguments. When the optional keyword argument ``quiet`` is True, it does
+   not fail if a filter catches nothing. Without argument, it defaults to::
+
+      check_warnings(("", Warning), quiet=False)
+
+   The main difference is that it verifies the warnings raised. If some filter
+   did not catch any warning, the test fails. If some warnings are not caught,
+   the test fails, too. To disable these checks, use argument ``quiet=True``.
+
+   Another significant difference is that on entry to the context manager, a
    :class:`WarningRecorder` instance is returned instead of a simple list.
    The underlying warnings list is available via the recorder object's
    :attr:`warnings` attribute, while the attributes of the last raised
@@ -308,20 +311,49 @@ The :mod:`test.test_support` module defines the following functions:
    A :meth:`reset` method is also provided on the recorder object. This
    method simply clears the warning list.
 
-   The context manager is used like this::
+   The context manager may be used like this::
 
-      with check_warnings() as w:
+      import warnings
+
+      with check_warnings():
+          exec('assert(False, "Hey!")')
+          warnings.warn(UserWarning("Hide me!"))
+
+      with check_warnings(("assertion is always true", SyntaxWarning),
+                          ("", UserWarning)):
+          exec('assert(False, "Hey!")')
+          warnings.warn(UserWarning("Hide me!"))
+
+      with check_warnings(quiet=True) as w:
           warnings.simplefilter("always")
           warnings.warn("foo")
-          assert str(w.message) == "foo"
+          assert str(w.args[0]) == "foo"
           warnings.warn("bar")
-          assert str(w.message) == "bar"
-          assert str(w.warnings[0].message) == "foo"
-          assert str(w.warnings[1].message) == "bar"
+          assert str(w.args[0]) == "bar"
+          assert str(w.warnings[0].args[0]) == "foo"
+          assert str(w.warnings[1].args[0]) == "bar"
           w.reset()
           assert len(w.warnings) == 0
 
    .. versionadded:: 2.6
+   .. versionchanged:: 2.7
+      The test fails when the context manager do not catch any warning.
+      New optional attributes ``*filters`` and ``quiet``.
+
+
+.. function:: check_py3k_warnings(*filters, quiet=False)
+
+   Same as :func:`check_warnings` but for Python 3 compatibility warnings.
+   If ``sys.py3kwarning == 1``, it checks if the warning is effectively raised.
+   If ``sys.py3kwarning == 0``, it checks that no warning is raised.
+
+   It accepts 2-tuples ``("message regexp", WarningCategory)`` as positional
+   arguments. When the optional keyword argument ``quiet`` is True, it does
+   not fail if a filter catches nothing. Without argument, it defaults to::
+
+      check_py3k_warnings(("", DeprecationWarning), quiet=False)
+
+   .. versionadded:: 2.7
 
 
 .. function:: captured_stdout()

Lib/test/test_support.py

@@ -539,11 +539,11 @@ def _filterwarnings(filters, quiet=False):
         if not seen and not quiet:
             # This filter caught nothing
             missing.append((msg, cat.__name__))
-    for exc in reraise:
-        raise AssertionError("unhandled warning %r" % exc)
-    for filter in missing:
-        raise AssertionError("filter (%r, %s) did not caught any warning" %
-                             filter)
+    if reraise:
+        raise AssertionError("unhandled warning %r" % reraise[0])
+    if missing:
+        raise AssertionError("filter (%r, %s) did not catch any warning" %
+                             missing[0])
 
 
 @contextlib.contextmanager