Index: Doc/library/test.rst
===================================================================
--- Doc/library/test.rst	(revision 88219)
+++ Doc/library/test.rst	(working copy)
@@ -233,6 +233,7 @@
    Set to a name that is safe to use as the name of a temporary file.  Any
    temporary file that is created should be closed and unlinked (removed).
 
+
 The :mod:`test.support` module defines the following functions:
 
 
@@ -281,6 +282,15 @@
    This will run all tests defined in the named module.
 
 
+.. function:: run_doctest(module, verbosity=None)
+
+   Run :mod:`doctest` on the given *module*.  Return
+   ``(failure_count, test_count)``.
+
+   If *verbosity* is :const:`None`, :meth:`doctest` is run with verbosity set
+   to :data:`verbose`.  Otherwise, it is run with verbosity set to
+   :const:`None`.
+
 .. function:: check_warnings(\*filters, quiet=True)
 
    A convenience wrapper for :func:`warnings.catch_warnings()` that makes it
@@ -349,7 +359,7 @@
 
 .. function:: captured_stdout()
 
-   This is a context manager that runs the :keyword:`with` statement body using
+   A context manager that 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.
 
@@ -360,6 +370,51 @@
       assert s.getvalue() == "hello"
 
 
+.. function:: temp_cwd(name='tempcwd', quiet=False, path=None)
+
+   A context manager that temporarily changes the current working
+   directory (CWD).
+
+   An existing path may be provided as *path*, in which case this function
+   makes no changes to the file system.
+
+   Otherwise, the new CWD is created in the current directory and it's named
+   *name*.  If *quiet* is :const:`False` and it's not possible to create or
+   change the CWD, an error is raised.  If it's :const:`True`, only a warning
+   is raised and the original CWD is used.
+
+
+.. function:: temp_umask(umask)
+
+   A context manager that temporarily sets the process umask to the
+   given value.
+
+
+.. function:: can_symlink()
+
+   Return :const:`True` if the OS supports symbolic links, :const:`False`
+   otherwise.
+
+
+.. function:: skip_unless_symlink()
+
+   A decorator for running tests that require support for symbolic links.
+
+
+.. function:: run_with_locale(catstr, *locales)
+
+   A decorator for running a function in a different locale, correctly
+   resetting it after it has finished.  *catstr* is the locale category as
+   a string (for example ``"LC_ALL"``).  The *locales* passed will be tried
+   sequentially, and the first valid locale will be used.
+
+
+.. function:: make_bad_fd()
+
+   Create an invalid file descriptor by opening and closing a temporary file,
+   and returning its descripor.
+
+
 .. function:: import_module(name, deprecated=False)
 
    This function imports and returns the named module. Unlike a normal
@@ -408,6 +463,46 @@
    .. versionadded:: 3.1
 
 
+.. function:: bind_port(sock, host=HOST)
+
+   Bind the socket to a free port and return the port number.  Relies on
+   ephemeral ports in order to ensure we are using an unbound port.  This is
+   important as many tests may be running simultaneously, especially in a
+   buildbot environment.  This method raises an exception if the
+   ``sock.family`` is :const:`AF_INET` and ``sock.type`` is
+   :const:`SOCK_STREAM`, and the socket has :const:`SO_REUSEADDR` or
+   :const:`SO_REUSEPORT` set on it.  Tests should never set these socket
+   options for TCP/IP sockets.  The only case for setting these options is
+   testing multicasting via multiple UDP sockets.
+
+   Additionally, if the :const:`SO_EXCLUSIVEADDRUSE` socket option is
+   available (i.e. on Windows), it will be set on the socket.  This will
+   prevent anyone else from binding to our host/port for the duration of the
+   test.
+
+
+.. function:: find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)
+
+   Returns an unused port that should be suitable for binding.  This is
+   achieved by creating a temporary socket with the same family and type as
+   the ``sock`` parameter (default is :const:`AF_INET`, :const:`SOCK_STREAM`),
+   and binding it to the specified host address (defaults to ``0.0.0.0``)
+   with the port set to 0, eliciting an unused ephemeral port from the OS.
+   The temporary socket is then closed and deleted, and the ephemeral port is
+   returned.
+
+   Either this method or :func:`bind_port` should be used for any tests
+   where a server socket needs to be bound to a particular port for the
+   duration of the test.
+   Which one to use depends on whether the calling code is creating a python
+   socket, or if an unused port needs to be provided in a constructor
+   or passed to an external program (i.e. the ``-accept`` argument to
+   openssl's s_server mode).  Always prefer :func:`bind_port` over
+   :func:`find_unused_port` where possible.  Using a hard coded port is
+   discouraged since it can makes multiple instances of the test impossible to
+   run simultaneously, which is a problem for buildbots.
+
+
 The :mod:`test.support` module defines the following classes:
 
 .. class:: TransientResource(exc, **kwargs)