rest25/library/test.rst => rest262/library/test.rst
9
10The :mod:`test` package contains all regression tests for Python as well as the
11modules :mod:`test.test_support` and :mod:`test.regrtest`.
12:mod:`test.test_support` is used to enhance your tests while
13:mod:`test.regrtest` drives the testing suite.
14
15Each module in the :mod:`test` package whose name starts with ``test_`` is a
16testing suite for a specific module or feature. All new tests should be written
n17-using the :mod:`unittest` module; using :mod:`unittest` is not required but
n17+using the :mod:`unittest` or :mod:`doctest` module.  Some older tests are
18-makes the tests more flexible and maintenance of the tests easier.  Some older
18+written using a "traditional" testing style that compares output printed to
19-tests are written to use :mod:`doctest` and a "traditional" testing style; these
19+``sys.stdout``; this style of test is considered deprecated.
20-styles of tests will not be covered.
21
22
23.. seealso::
24
25   Module :mod:`unittest`
26      Writing PyUnit regression tests.
27
28   Module :mod:`doctest`
29      Tests embedded in documentation strings.
30
31
32.. _writing-tests:
33
34Writing Unit Tests for the :mod:`test` package
35----------------------------------------------
36
n37-.. % 
n36+It is preferred that tests that use the :mod:`unittest` module follow a few
38- 
37+guidelines. One is to name the test module by starting it with ``test_`` and end
39-It is preferred that tests for the :mod:`test` package use the :mod:`unittest`
38+it with the name of the module being tested. The test methods in the test module
40-module and follow a few guidelines. One is to name the test module by starting
39+should start with ``test_`` and end with a description of what the method is
41-it with ``test_`` and end it with the name of the module being tested. The test
40+testing. This is needed so that the methods are recognized by the test driver as
42-methods in the test module should start with ``test_`` and end with a
41+test methods. Also, no documentation string for the method should be included. A
43-description of what the method is testing. This is needed so that the methods
42+comment (such as ``# Tests function returns only True or False``) should be used
44-are recognized by the test driver as test methods. Also, no documentation string
43+to provide documentation for test methods. This is done because documentation
45-for the method should be included. A comment (such as ``# Tests function returns
44+strings get printed out if they exist and thus what test is being run is not
46-only True or False``) should be used to provide documentation for test methods.
45+stated.
47-This is done because documentation strings get printed out if they exist and
48-thus what test is being run is not stated.
49
50A basic boilerplate is often used::
51
52   import unittest
53   from test import test_support
54
55   class MyTestCase1(unittest.TestCase):
56
183
184
185:mod:`test.test_support` --- Utility functions for tests
186========================================================
187
188.. module:: test.test_support
189   :synopsis: Support for Python regression tests.
190
n188+.. note::
189+ 
190+   The :mod:`test.test_support` module has been renamed to :mod:`test.support`
191+   in Python 3.0.  The :term:`2to3` tool will automatically adapt imports when
192+   converting your sources to 3.0.
193+ 
194+ 
195+ 
191
192The :mod:`test.test_support` module provides support for Python's regression
193tests.
194
195This module defines the following exceptions:
196
197
198.. exception:: TestFailed
199
n200-   Exception to be raised when a test fails.
n205+   Exception to be raised when a test fails. This is deprecated in favor of
206+   :mod:`unittest`\ -based tests and :class:`unittest.TestCase`'s assertion
207+   methods.
201
202
203.. exception:: TestSkipped
204
205   Subclass of :exc:`TestFailed`. Raised when a test is skipped. This occurs when a
206   needed resource (such as a network connection) is not available at the time of
207   testing.
208
266   Return the path to the file named *filename*. If no match is found *filename* is
267   returned. This does not equal a failure since it could be the path to the file.
268
269
270.. function:: run_unittest(*classes)
271
272   Execute :class:`unittest.TestCase` subclasses passed to the function. The
273   function scans the classes for methods starting with the prefix ``test_`` and
n274-   executes the tests individually. This is the preferred way to execute tests.
n281+   executes the tests individually.
275
n283+   It is also legal to pass strings as parameters; these should be keys in
284+   ``sys.modules``. Each associated module will be scanned by
285+   ``unittest.TestLoader.loadTestsFromModule()``. This is usually seen in the
286+   following :func:`test_main` function::
276
n277-.. function:: run_suite(suite[, testclass])
n288+      def test_main():
289+          test_support.run_unittest(__name__)
278
n279-   Execute the :class:`unittest.TestSuite` instance *suite*. The optional argument
n291+   This will run all tests defined in the named module.
280-   *testclass* accepts one of the test classes in the suite so as to print out more
281-   detailed information on where the testing suite originated from.
282
t293+ 
294+.. function:: check_warnings()
295+ 
296+   A convenience wrapper for ``warnings.catch_warnings()`` that makes
297+   it easier to test that a warning was correctly raised with a single
298+   assertion. It is approximately equivalent to calling
299+   ``warnings.catch_warnings(record=True)``.
300+ 
301+   The main difference is that on entry to the context manager, a
302+   :class:`WarningRecorder` instance is returned instead of a simple list.
303+   The underlying warnings list is available via the recorder object's
304+   :attr:`warnings` attribute, while the attributes of the last raised
305+   warning are also accessible directly on the object. If no warning has
306+   been raised, then the latter attributes will all be :const:`None`.
307+ 
308+   A :meth:`reset` method is also provided on the recorder object. This
309+   method simply clears the warning list.
310+ 
311+   The context manager is used like this::
312+ 
313+      with check_warnings() as w:
314+          warnings.simplefilter("always")
315+          warnings.warn("foo")
316+          assert str(w.message) == "foo"
317+          warnings.warn("bar")
318+          assert str(w.message) == "bar"
319+          assert str(w.warnings[0].message) == "foo"
320+          assert str(w.warnings[1].message) == "bar"
321+          w.reset()
322+          assert len(w.warnings) == 0
323+ 
324+   .. versionadded:: 2.6
325+ 
326+ 
327+.. function:: captured_stdout()
328+ 
329+   This is a context manager than runs the :keyword:`with` statement body using
330+   a :class:`StringIO.StringIO` object as sys.stdout.  That object can be
331+   retrieved using the ``as`` clause of the :keyword:`with` statement.
332+ 
333+   Example use::
334+ 
335+      with captured_stdout() as s:
336+          print "hello"
337+      assert s.getvalue() == "hello"
338+ 
339+   .. versionadded:: 2.6
340+ 
341+ 
342+The :mod:`test.test_support` module defines the following classes:
343+ 
344+.. class:: TransientResource(exc[, **kwargs])
345+ 
346+   Instances are a context manager that raises :exc:`ResourceDenied` if the
347+   specified exception type is raised.  Any keyword arguments are treated as
348+   attribute/value pairs to be compared against any exception raised within the
349+   :keyword:`with` statement.  Only if all pairs match properly against
350+   attributes on the exception is :exc:`ResourceDenied` raised.
351+ 
352+   .. versionadded:: 2.6
353+.. class:: EnvironmentVarGuard()
354+ 
355+   Class used to temporarily set or unset environment variables.  Instances can be
356+   used as a context manager.
357+ 
358+   .. versionadded:: 2.6
359+ 
360+ 
361+.. method:: EnvironmentVarGuard.set(envvar, value)
362+ 
363+   Temporarily set the environment variable ``envvar`` to the value of ``value``.
364+ 
365+ 
366+.. method:: EnvironmentVarGuard.unset(envvar)
367+ 
368+   Temporarily unset the environment variable ``envvar``.
369+ 
370+.. class:: WarningsRecorder()
371+ 
372+   Class used to record warnings for unit tests. See documentation of
373+   :func:`check_warnings` above for more details.
374+ 
375+   .. versionadded:: 2.6
376+ 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op