| |
| The :mod:`test` package contains all regression tests for Python as well as the |
| modules :mod:`test.test_support` and :mod:`test.regrtest`. |
| :mod:`test.test_support` is used to enhance your tests while |
| :mod:`test.regrtest` drives the testing suite. |
| |
| Each module in the :mod:`test` package whose name starts with ``test_`` is a |
| testing suite for a specific module or feature. All new tests should be written |
n | using the :mod:`unittest` module; using :mod:`unittest` is not required but |
n | using the :mod:`unittest` or :mod:`doctest` module. Some older tests are |
| makes the tests more flexible and maintenance of the tests easier. Some older |
| written using a "traditional" testing style that compares output printed to |
| tests are written to use :mod:`doctest` and a "traditional" testing style; these |
| ``sys.stdout``; this style of test is considered deprecated. |
| styles of tests will not be covered. |
| |
| |
| .. seealso:: |
| |
| Module :mod:`unittest` |
| Writing PyUnit regression tests. |
| |
| Module :mod:`doctest` |
| Tests embedded in documentation strings. |
| |
| |
| .. _writing-tests: |
| |
| Writing Unit Tests for the :mod:`test` package |
| ---------------------------------------------- |
| |
n | .. % |
n | It is preferred that tests that use the :mod:`unittest` module follow a few |
| |
| guidelines. One is to name the test module by starting it with ``test_`` and end |
| It is preferred that tests for the :mod:`test` package use the :mod:`unittest` |
| it with the name of the module being tested. The test methods in the test module |
| module and follow a few guidelines. One is to name the test module by starting |
| should start with ``test_`` and end with a description of what the method is |
| it with ``test_`` and end it with the name of the module being tested. The test |
| testing. This is needed so that the methods are recognized by the test driver as |
| methods in the test module should start with ``test_`` and end with a |
| test methods. Also, no documentation string for the method should be included. A |
| description of what the method is testing. This is needed so that the methods |
| comment (such as ``# Tests function returns only True or False``) should be used |
| are recognized by the test driver as test methods. Also, no documentation string |
| to provide documentation for test methods. This is done because documentation |
| for the method should be included. A comment (such as ``# Tests function returns |
| strings get printed out if they exist and thus what test is being run is not |
| only True or False``) should be used to provide documentation for test methods. |
| stated. |
| This is done because documentation strings get printed out if they exist and |
| thus what test is being run is not stated. |
| |
| A basic boilerplate is often used:: |
| |
| import unittest |
| from test import test_support |
| |
| class MyTestCase1(unittest.TestCase): |
| |
| |
| |
| :mod:`test.test_support` --- Utility functions for tests |
| ======================================================== |
| |
| .. module:: test.test_support |
| :synopsis: Support for Python regression tests. |
| |
n | .. note:: |
| |
| The :mod:`test.test_support` module has been renamed to :mod:`test.support` |
| in Python 3.0. The :term:`2to3` tool will automatically adapt imports when |
| converting your sources to 3.0. |
| |
| |
| |
| |
| The :mod:`test.test_support` module provides support for Python's regression |
| tests. |
| |
| This module defines the following exceptions: |
| |
| |
| .. exception:: TestFailed |
| |
n | Exception to be raised when a test fails. |
n | Exception to be raised when a test fails. This is deprecated in favor of |
| :mod:`unittest`\ -based tests and :class:`unittest.TestCase`'s assertion |
| 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. |
| |
| Return the path to the file named *filename*. If no match is found *filename* is |
| returned. This does not equal a failure since it could be the path to the file. |
| |
| |
| .. function:: run_unittest(*classes) |
| |
| Execute :class:`unittest.TestCase` subclasses passed to the function. The |
| function scans the classes for methods starting with the prefix ``test_`` and |
n | executes the tests individually. This is the preferred way to execute tests. |
n | executes the tests individually. |
| |
n | It is also legal to pass strings as parameters; these should be keys in |
| ``sys.modules``. Each associated module will be scanned by |
| ``unittest.TestLoader.loadTestsFromModule()``. This is usually seen in the |
| following :func:`test_main` function:: |
| |
n | .. function:: run_suite(suite[, testclass]) |
n | def test_main(): |
| test_support.run_unittest(__name__) |
| |
n | Execute the :class:`unittest.TestSuite` instance *suite*. The optional argument |
n | This will run all tests defined in the named module. |
| *testclass* accepts one of the test classes in the suite so as to print out more |
| detailed information on where the testing suite originated from. |
| |
t | |
| .. function:: check_warnings() |
| |
| 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 |
| :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 |
| warning are also accessible directly on the object. If no warning has |
| been raised, then the latter attributes will all be :const:`None`. |
| |
| 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:: |
| |
| with check_warnings() as w: |
| warnings.simplefilter("always") |
| warnings.warn("foo") |
| assert str(w.message) == "foo" |
| warnings.warn("bar") |
| assert str(w.message) == "bar" |
| assert str(w.warnings[0].message) == "foo" |
| assert str(w.warnings[1].message) == "bar" |
| w.reset() |
| assert len(w.warnings) == 0 |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. function:: captured_stdout() |
| |
| This is a context manager than runs the :keyword:`with` statement body using |
| a :class:`StringIO.StringIO` object as sys.stdout. That object can be |
| retrieved using the ``as`` clause of the :keyword:`with` statement. |
| |
| Example use:: |
| |
| with captured_stdout() as s: |
| print "hello" |
| assert s.getvalue() == "hello" |
| |
| .. versionadded:: 2.6 |
| |
| |
| The :mod:`test.test_support` module defines the following classes: |
| |
| .. class:: TransientResource(exc[, **kwargs]) |
| |
| Instances are a context manager that raises :exc:`ResourceDenied` if the |
| specified exception type is raised. Any keyword arguments are treated as |
| attribute/value pairs to be compared against any exception raised within the |
| :keyword:`with` statement. Only if all pairs match properly against |
| attributes on the exception is :exc:`ResourceDenied` raised. |
| |
| .. versionadded:: 2.6 |
| .. class:: EnvironmentVarGuard() |
| |
| Class used to temporarily set or unset environment variables. Instances can be |
| used as a context manager. |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. method:: EnvironmentVarGuard.set(envvar, value) |
| |
| Temporarily set the environment variable ``envvar`` to the value of ``value``. |
| |
| |
| .. method:: EnvironmentVarGuard.unset(envvar) |
| |
| Temporarily unset the environment variable ``envvar``. |
| |
| .. class:: WarningsRecorder() |
| |
| Class used to record warnings for unit tests. See documentation of |
| :func:`check_warnings` above for more details. |
| |
| .. versionadded:: 2.6 |
| |