diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/test.rst | 78 |
1 files changed, 55 insertions, 23 deletions
diff --git a/Doc/library/test.rst b/Doc/library/test.rst index b4a6c7a..86f0af3 100644 --- a/Doc/library/test.rst +++ b/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:: + + 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() as w: + 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() |