--- rest25/library/test.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/test.rst	2009-04-05 05:02:09.000000000 +0900
@@ -5,56 +5,53 @@
 .. module:: test
    :synopsis: Regression tests package containing the testing suite for Python.
 .. sectionauthor:: Brett Cannon <brett@python.org>
 
 
 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
-using the :mod:`unittest` module; using :mod:`unittest` is not required but
-makes the tests more flexible and maintenance of the tests easier.  Some older
-tests are written to use :mod:`doctest` and a "traditional" testing style; these
-styles of tests will not be covered.
+using the :mod:`unittest` or :mod:`doctest` module.  Some older tests are
+written using a "traditional" testing style that compares output printed to
+``sys.stdout``; this style of test is considered deprecated.
 
 
 .. 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
 ----------------------------------------------
 
-.. % 
-
-It is preferred that tests for the :mod:`test` package use the :mod:`unittest`
-module and follow a few guidelines.
+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 with the name of the module being tested.
+One is to name the test module by starting it with ``test_`` and end
+it with the name of the module being tested.
-The test
-methods in the test module should start with ``test_`` and end with a
-description of what the method is testing.
+The test methods in the test module
+should start with ``test_`` and end with a description of what the method is
+testing.
-This is needed so that the methods
-are recognized by the test driver as test methods.
+This is needed so that the methods are recognized by the test driver as
+test methods.
-Also, no documentation string
-for the method should be included.
+Also, no documentation string for the method should be included.
-A comment (such as ``# Tests function returns
-only True or False``) should be used to provide documentation for test methods.
+A
+comment (such as ``# Tests function returns only True or False``) should be used
+to provide documentation for test methods.
-This is done because documentation strings get printed out if they exist and
-thus what test is being run is not 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):
 
        # Only use setUp() and tearDown() if necessary
 
        def setUp(self):
            ... code to execute in preparation for tests ...
@@ -179,34 +176,44 @@
 tests are being executed on. On Unix, you can run :program:`make` :option:`test`
 at the top-level directory where Python was built. On Windows, executing
 :program:`rt.bat` from your :file:`PCBuild` directory will run all regression
 tests.
 
 
 :mod:`test.test_support` --- Utility functions for tests
 ========================================================
 
 .. module:: test.test_support
    :synopsis: Support for Python regression tests.
 
+.. 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
 
-   Exception to be raised when a test fails.
+   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.
 
 
 .. exception:: ResourceDenied
 
    Subclass of :exc:`TestSkipped`. Raised when a resource (such as a network
@@ -262,21 +269,108 @@
 
 
 .. function:: findfile(filename)
 
    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
-   executes the tests individually. This is the preferred way to execute tests.
+   executes the tests individually.
+
+   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::
+
+      def test_main():
+          test_support.run_unittest(__name__)
+
+   This will run all tests defined in the named module.
+
+
+.. 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()
 
-.. function:: run_suite(suite[, testclass])
+   Class used to record warnings for unit tests. See documentation of
+   :func:`check_warnings` above for more details.
 
-   Execute the :class:`unittest.TestSuite` instance *suite*. The optional argument
-   *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.
+   .. versionadded:: 2.6
 
