Patch #1534922: correct and enhance unittest docs.

Doc/lib/libunittest.tex

@@ -10,19 +10,19 @@
 
 \versionadded{2.1}
 
-The Python unit testing framework, often referred to as ``PyUnit,'' is
+The Python unit testing framework, sometimes referred to as ``PyUnit,'' is
 a Python language version of JUnit, by Kent Beck and Erich Gamma.
 JUnit is, in turn, a Java version of Kent's Smalltalk testing
 framework.  Each is the de facto standard unit testing framework for
 its respective language.
 
-PyUnit supports test automation, sharing of setup and shutdown code
+\module{unittest} supports test automation, sharing of setup and shutdown
-for tests, aggregation of tests into collections, and independence of
+code for tests, aggregation of tests into collections, and independence of
 the tests from the reporting framework.  The \module{unittest} module
 provides classes that make it easy to support these qualities for a
 set of tests.
 
-To achieve this, PyUnit supports some important concepts:
+To achieve this, \module{unittest} supports some important concepts:
 
 \begin{definitions}
 \term{test fixture}
@@ -33,10 +33,9 @@ starting a server process.
 
 \term{test case}
 A \dfn{test case} is the smallest unit of testing.  It checks for a
-specific response to a particular set of inputs.  PyUnit provides a
+specific response to a particular set of inputs.  \module{unittest}
-base class, \class{TestCase}, which may be used to create new test
+provides a base class, \class{TestCase}, which may be used to create
-cases. You may provide your own implementation that does not subclass
+new test cases.
-from \class{TestCase}, of course.
 
 \term{test suite}
 A \dfn{test suite} is a collection of test cases, test suites, or
@@ -54,8 +53,8 @@ indicate the results of executing the tests.
 The test case and test fixture concepts are supported through the
 \class{TestCase} and \class{FunctionTestCase} classes; the former
 should be used when creating new tests, and the latter can be used when
-integrating existing test code with a PyUnit-driven framework.  When
+integrating existing test code with a \module{unittest}-driven framework.
-building test fixtures using \class{TestCase}, the \method{setUp()}
+When building test fixtures using \class{TestCase}, the \method{setUp()}
 and \method{tearDown()} methods can be overridden to provide
 initialization and cleanup for the fixture.  With
 \class{FunctionTestCase}, existing functions can be passed to the
@@ -74,19 +73,17 @@ the suite is executed, all tests added directly to the suite and in
 A test runner is an object that provides a single method,
 \method{run()}, which accepts a \class{TestCase} or \class{TestSuite}
 object as a parameter, and returns a result object.  The class
-\class{TestResult} is provided for use as the result object.  PyUnit
+\class{TestResult} is provided for use as the result object.
-provide the \class{TextTestRunner} as an example test runner which
+\module{unittest} provides the \class{TextTestRunner} as an example
-reports test results on the standard error stream by default.
+test runner which reports test results on the standard error stream by
-Alternate runners can be implemented for other environments (such as
+default.  Alternate runners can be implemented for other environments
-graphical environments) without any need to derive from a specific
+(such as graphical environments) without any need to derive from a
-class.
+specific class.
 
 
 \begin{seealso}
   \seemodule{doctest}{Another test-support module with a very
                       different flavor.}
-  \seetitle[http://pyunit.sourceforge.net/]{PyUnit Web Site}{The
-            source for further information on PyUnit.}
   \seetitle[http://www.XProgramming.com/testfram.htm]{Simple Smalltalk
             Testing: With Patterns}{Kent Beck's original paper on
             testing frameworks using the pattern shared by
@@ -166,7 +163,7 @@ run from the command line.  For example, the last two lines may be replaced
 with:
 
 \begin{verbatim}
-suite = unittest.makeSuite(TestSequenceFunctions)
+suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions)
 unittest.TextTestRunner(verbosity=2).run(suite)
 \end{verbatim}
 
@@ -194,8 +191,8 @@ of the documentation explores the full feature set from first principles.
 
 The basic building blocks of unit testing are \dfn{test cases} ---
 single scenarios that must be set up and checked for correctness.  In
-PyUnit, test cases are represented by instances of the
+\module{unittest}, test cases are represented by instances of
-\class{TestCase} class in the \refmodule{unittest} module. To make
+\module{unittest}'s \class{TestCase} class. To make
 your own test cases you must write subclasses of \class{TestCase}, or
 use \class{FunctionTestCase}.
 
@@ -207,7 +204,7 @@ The testing code of a \class{TestCase} instance should be entirely
 self contained, such that it can be run either in isolation or in
 arbitrary combination with any number of other test cases.
 
-The simplest test case subclass will simply override the
+The simplest \class{TestCase} subclass will simply override the
 \method{runTest()} method in order to perform specific testing code:
 
 \begin{verbatim}
@@ -221,12 +218,13 @@ class DefaultWidgetSizeTestCase(unittest.TestCase):
 
 Note that in order to test something, we use the one of the
 \method{assert*()} or \method{fail*()} methods provided by the
-\class{TestCase} base class.  If the test fails when the test case
+\class{TestCase} base class.  If the test fails, an exception will be
-runs, an exception will be raised, and the testing framework will
+raised, and \module{unittest} will identify the test case as a
-identify the test case as a \dfn{failure}.  Other exceptions that do
+\dfn{failure}.  Any other exceptions will be treated as \dfn{errors}.
-not arise from checks made through the \method{assert*()} and
+This helps you identify where the problem is: \dfn{failures} are caused by
-\method{fail*()} methods are identified by the testing framework as
+incorrect results - a 5 where you expected a 6. \dfn{Errors} are caused by
-\dfn{errors}.
+incorrect code - e.g., a \exception{TypeError} caused by an incorrect
+function call.
 
 The way to run a test case will be described later.  For now, note
 that to construct an instance of such a test case, we call its
@@ -237,7 +235,7 @@ testCase = DefaultWidgetSizeTestCase()
 \end{verbatim}
 
 Now, such test cases can be numerous, and their set-up can be
-repetitive.  In the above case, constructing a ``Widget'' in each of
+repetitive.  In the above case, constructing a \class{Widget} in each of
 100 Widget test case subclasses would mean unsightly duplication.
 
 Luckily, we can factor out such set-up code by implementing a method
@@ -283,7 +281,7 @@ class SimpleWidgetTestCase(unittest.TestCase):
 \end{verbatim}
 
 If \method{setUp()} succeeded, the \method{tearDown()} method will be
-run regardless of whether or not \method{runTest()} succeeded.
+run whether \method{runTest()} succeeded or not.
 
 Such a working environment for the testing code is called a
 \dfn{fixture}.
@@ -292,8 +290,8 @@ Often, many small test cases will use the same fixture.  In this case,
 we would end up subclassing \class{SimpleWidgetTestCase} into many
 small one-method classes such as
 \class{DefaultWidgetSizeTestCase}.  This is time-consuming and
-discouraging, so in the same vein as JUnit, PyUnit provides a simpler
+discouraging, so in the same vein as JUnit, \module{unittest} provides
-mechanism:
+a simpler mechanism:
 
 \begin{verbatim}
 import unittest
@@ -329,9 +327,9 @@ resizeTestCase = WidgetTestCase("testResize")
 \end{verbatim}
 
 Test case instances are grouped together according to the features
-they test.  PyUnit provides a mechanism for this: the \class{test
+they test.  \module{unittest} provides a mechanism for this: the
-suite}, represented by the class \class{TestSuite} in the
+\dfn{test suite}, represented by \module{unittest}'s \class{TestSuite}
-\refmodule{unittest} module:
+class:
 
 \begin{verbatim}
 widgetTestSuite = unittest.TestSuite()
@@ -354,28 +352,30 @@ def suite():
 or even:
 
 \begin{verbatim}
-class WidgetTestSuite(unittest.TestSuite):
+def suite():
-    def __init__(self):
+    tests = ["testDefaultSize", "testResize"]
-        unittest.TestSuite.__init__(self,map(WidgetTestCase,
-                                              ("testDefaultSize",
-                                               "testResize")))
-\end{verbatim}
 
-(The latter is admittedly not for the faint-hearted!)
+    return unittest.TestSuite(map(WidgetTestCase, tests))
+\end{verbatim}
 
 Since it is a common pattern to create a \class{TestCase} subclass
-with many similarly named test functions, there is a convenience
+with many similarly named test functions, \module{unittest} provides a
-function called \function{makeSuite()} that constructs a test suite
+\class{TestLoader} class that can be used to automate the process of
-that comprises all of the test cases in a test case class:
+creating a test suite and populating it with individual tests.
+For example,
 
 \begin{verbatim}
-suite = unittest.makeSuite(WidgetTestCase)
+suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)
 \end{verbatim}
 
-Note that when using the \function{makeSuite()} function, the order in
+will create a test suite that will run
-which the various test cases will be run by the test suite is the
+\code{WidgetTestCase.testDefaultSize()} and \code{WidgetTestCase.testResize}.
-order determined by sorting the test function names using the
+\class{TestLoader} uses the \code{'test'} method name prefix to identify
-\function{cmp()} built-in function.
+test methods automatically.
+
+Note that the order in which the various test cases will be run is
+determined by sorting the test function names with the built-in
+\function{cmp()} function.
 
 Often it is desirable to group suites of test cases together, so as to
 run tests for the whole system at once.  This is easy, since
@@ -385,13 +385,13 @@ as \class{TestCase} instances can be added to a \class{TestSuite}:
 \begin{verbatim}
 suite1 = module1.TheTestSuite()
 suite2 = module2.TheTestSuite()
-alltests = unittest.TestSuite((suite1, suite2))
+alltests = unittest.TestSuite([suite1, suite2])
 \end{verbatim}
 
 You can place the definitions of test cases and test suites in the
 same modules as the code they are to test (such as \file{widget.py}),
 but there are several advantages to placing the test code in a
-separate module, such as \file{widgettests.py}:
+separate module, such as \file{test_widget.py}:
 
 \begin{itemize}
   \item The test module can be run standalone from the command line.
@@ -412,13 +412,12 @@ separate module, such as \file{widgettests.py}:
             \label{legacy-unit-tests}}
 
 Some users will find that they have existing test code that they would
-like to run from PyUnit, without converting every old test function to
+like to run from \module{unittest}, without converting every old test
-a \class{TestCase} subclass.
+function to a \class{TestCase} subclass.
 
-For this reason, PyUnit provides a \class{FunctionTestCase} class.
+For this reason, \module{unittest} provides a \class{FunctionTestCase}
-This subclass of \class{TestCase} can be used to wrap an existing test
+class.  This subclass of \class{TestCase} can be used to wrap an existing
-function.  Set-up and tear-down functions can also optionally be
+test function.  Set-up and tear-down functions can also be provided.
-wrapped.
 
 Given the following test function:
 
@@ -436,7 +435,8 @@ testcase = unittest.FunctionTestCase(testSomething)
 \end{verbatim}
 
 If there are additional set-up and tear-down methods that should be
-called as part of the test case's operation, they can also be provided:
+called as part of the test case's operation, they can also be provided
+like so:
 
 \begin{verbatim}
 testcase = unittest.FunctionTestCase(testSomething,
@@ -444,9 +444,19 @@ testcase = unittest.FunctionTestCase(testSomething,
                                      tearDown=deleteSomethingDB)
 \end{verbatim}
 
-\note{PyUnit supports the use of \exception{AssertionError}
+To make migrating existing test suites easier, \module{unittest}
-as an indicator of test failure, but does not recommend it.  Future
+supports tests raising \exception{AssertionError} to indicate test failure.
-versions may treat \exception{AssertionError} differently.}
+However, it is recommended that you use the explicit
+\method{TestCase.fail*()} and \method{TestCase.assert*()} methods instead,
+as future versions of \module{unittest} may treat \exception{AssertionError}
+differently.
+
+\note{Even though \class{FunctionTestCase} can be used to quickly convert
+an existing test base over to a \module{unittest}-based system, this
+approach is not recommended.  Taking the time to set up proper
+\class{TestCase} subclasses will make future test refactorings infinitely
+easier.}
+
 
 
 \subsection{Classes and functions
@@ -454,11 +464,12 @@ versions may treat \exception{AssertionError} differently.}
 
 \begin{classdesc}{TestCase}{}
   Instances of the \class{TestCase} class represent the smallest
-  testable units in a set of tests.  This class is intended to be used
+  testable units in the \module{unittest} universe.  This class is
-  as a base class, with specific tests being implemented by concrete
+  intended to be used as a base class, with specific tests being
-  subclasses.  This class implements the interface needed by the test
+  implemented by concrete subclasses.  This class implements the
-  runner to allow it to drive the test, and methods that the test code
+  interface needed by the test runner to allow it to drive the
-  can use to check for and report various kinds of failures.
+  test, and methods that the test code can use to check for and
+  report various kinds of failure.
 \end{classdesc}
 
 \begin{classdesc}{FunctionTestCase}{testFunc\optional{,
@@ -474,33 +485,33 @@ versions may treat \exception{AssertionError} differently.}
 \begin{classdesc}{TestSuite}{\optional{tests}}
   This class represents an aggregation of individual tests cases and
   test suites.  The class presents the interface needed by the test
-  runner to allow it to be run as any other test case, but all the
+  runner to allow it to be run as any other test case.  Running a
-  contained tests and test suites are executed.  Additional methods
+  \class{TestSuite} instance is the same as iterating over the suite,
-  are provided to add test cases and suites to the aggregation.  If
+  running each test individually.
-  \var{tests} is given, it must be a sequence of individual tests that
+  
-  will be added to the suite.
+  If \var{tests} is given, it must be an iterable of individual test cases or
+  other test suites that will be used to build the suite initially.
+  Additional methods are provided to add test cases and suites to the
+  collection later on.
 \end{classdesc}
 
 \begin{classdesc}{TestLoader}{}
   This class is responsible for loading tests according to various
   criteria and returning them wrapped in a \class{TestSuite}.
   It can load all tests within a given module or \class{TestCase}
-  class.  When loading from a module, it considers all
+  subclass.
-  \class{TestCase}-derived classes.  For each such class, it creates
-  an instance for each method with a name beginning with the string
-  \samp{test}.
 \end{classdesc}
 
 \begin{datadesc}{defaultTestLoader}
-  Instance of the \class{TestLoader} class which can be shared.  If no
+  Instance of the \class{TestLoader} class intended to be shared.  If no
   customization of the \class{TestLoader} is needed, this instance can
-  always be used instead of creating new instances.
+  be used instead of repeatedly creating new instances.
 \end{datadesc}
 
 \begin{classdesc}{TextTestRunner}{\optional{stream\optional{,
                   descriptions\optional{, verbosity}}}}
   A basic test runner implementation which prints results on standard
-  output.  It has a few configurable parameters, but is essentially
+  error.  It has a few configurable parameters, but is essentially
   very simple.  Graphical applications which run test suites should
   provide alternate implementations.
 \end{classdesc}
@@ -510,7 +521,8 @@ versions may treat \exception{AssertionError} differently.}
                  testRunner\optional{, testRunner}}}}}}
   A command-line program that runs a set of tests; this is primarily
   for making test modules conveniently executable.  The simplest use
-  for this function is:
+  for this function is to include the following line at the end of a
+  test script:
 
 \begin{verbatim}
 if __name__ == '__main__':
@@ -518,10 +530,11 @@ if __name__ == '__main__':
 \end{verbatim}
 \end{funcdesc}
 
-In some cases, the existing tests may have be written using the
+In some cases, the existing tests may have been written using the
 \refmodule{doctest} module.  If so, that module provides a 
 \class{DocTestSuite} class that can automatically build
-\class{unittest.TestSuite} instances from the existing test code.
+\class{unittest.TestSuite} instances from the existing
+\module{doctest}-based tests.
 \versionadded{2.3}
 
 
@@ -538,7 +551,7 @@ used to run the test, another used by the test implementation to
 check conditions and report failures, and some inquiry methods
 allowing information about the test itself to be gathered.
 
-Methods in the first group are:
+Methods in the first group (running the test) are:
 
 \begin{methoddesc}[TestCase]{setUp}{}
   Method called to prepare the test fixture.  This is called
@@ -562,8 +575,10 @@ Methods in the first group are:
   Run the test, collecting the result into the test result object
   passed as \var{result}.  If \var{result} is omitted or \constant{None},
   a temporary result object is created and used, but is not made
-  available to the caller.  This is equivalent to simply calling the
+  available to the caller.
-  \class{TestCase} instance.
+  
+  The same effect may be had by simply calling the \class{TestCase}
+  instance.
 \end{methoddesc}
 
 \begin{methoddesc}[TestCase]{debug}{}
@@ -664,10 +679,8 @@ Testing frameworks can use the following methods to collect
 information on the test:
 
 \begin{methoddesc}[TestCase]{countTestCases}{}
-  Return the number of tests represented by the this test object.  For
+  Return the number of tests represented by this test object.  For
-  \class{TestCase} instances, this will always be \code{1}, but this
+  \class{TestCase} instances, this will always be \code{1}.
-  method is also implemented by the \class{TestSuite} class, which can
-  return larger values.
 \end{methoddesc}
 
 \begin{methoddesc}[TestCase]{defaultTestResult}{}
@@ -678,7 +691,7 @@ information on the test:
 \begin{methoddesc}[TestCase]{id}{}
   Return a string identifying the specific test case.  This is usually
   the full name of the test method, including the module and class
-  names.
+  name.
 \end{methoddesc}
 
 \begin{methoddesc}[TestCase]{shortDescription}{}
@@ -694,21 +707,23 @@ information on the test:
 
 \class{TestSuite} objects behave much like \class{TestCase} objects,
 except they do not actually implement a test.  Instead, they are used
-to aggregate tests into groups that should be run together.  Some
+to aggregate tests into groups of tests that should be run together.
-additional methods are available to add tests to \class{TestSuite}
+Some additional methods are available to add tests to \class{TestSuite}
 instances:
 
 \begin{methoddesc}[TestSuite]{addTest}{test}
-  Add a \class{TestCase} or \class{TestSuite} to the set of tests that
+  Add a \class{TestCase} or \class{TestSuite} to the suite.
-  make up the suite.
 \end{methoddesc}
 
 \begin{methoddesc}[TestSuite]{addTests}{tests}
-  Add all the tests from a sequence of \class{TestCase} and
+  Add all the tests from an iterable of \class{TestCase} and
   \class{TestSuite} instances to this test suite.
+  
+  This is equivalent to iterating over \var{tests}, calling
+  \method{addTest()} for each element.
 \end{methoddesc}
 
-The \method{run()} method is also slightly different:
+\class{TestSuite} shares the following methods with \class{TestCase}:
 
 \begin{methoddesc}[TestSuite]{run}{result}
   Run the tests associated with this suite, collecting the result into
@@ -717,6 +732,17 @@ The \method{run()} method is also slightly different:
   result object to be passed in.
 \end{methoddesc}
 
+\begin{methoddesc}[TestSuite]{debug}{}
+  Run the tests associated with this suite without collecting the result.
+  This allows exceptions raised by the test to be propagated to the caller
+  and can be used to support running tests under a debugger.
+\end{methoddesc}
+
+\begin{methoddesc}[TestSuite]{countTestCases}{}
+  Return the number of tests represented by this test object, including
+  all individual tests and sub-suites.
+\end{methoddesc}
+
 In the typical usage of a \class{TestSuite} object, the \method{run()}
 method is invoked by a \class{TestRunner} rather than by the end-user
 test harness.
@@ -727,7 +753,7 @@ test harness.
 
 A \class{TestResult} object stores the results of a set of tests.  The
 \class{TestCase} and \class{TestSuite} classes ensure that results are
-properly stored; test authors do not need to worry about recording the
+properly recorded; test authors do not need to worry about recording the
 outcome of tests.
 
 Testing frameworks built on top of \refmodule{unittest} may want
@@ -745,28 +771,41 @@ formatted version of the traceback for the exception.
 be of interest when inspecting the results of running a set of tests:
 
 \begin{memberdesc}[TestResult]{errors}
-  A list containing pairs of \class{TestCase} instances and the
+  A list containing 2-tuples of \class{TestCase} instances and
-  formatted tracebacks for tests which raised an exception but did not
+  formatted tracebacks. Each tuple represents a test which raised an
-  signal a test failure.
+  unexpected exception.
   \versionchanged[Contains formatted tracebacks instead of
                   \function{sys.exc_info()} results]{2.2}
 \end{memberdesc}
 
 \begin{memberdesc}[TestResult]{failures}
-  A list containing pairs of \class{TestCase} instances and the
+  A list containing 2-tuples of \class{TestCase} instances and
-  formatted tracebacks for tests which signalled a failure in the code
+  formatted tracebacks. Each tuple represents a test where a failure
-  under test.
+  was explicitly signalled using the \method{TestCase.fail*()} or
+  \method{TestCase.assert*()} methods.
   \versionchanged[Contains formatted tracebacks instead of
                   \function{sys.exc_info()} results]{2.2}
 \end{memberdesc}
 
 \begin{memberdesc}[TestResult]{testsRun}
-  The number of tests which have been started.
+  The total number of tests run so far.
 \end{memberdesc}
 
 \begin{methoddesc}[TestResult]{wasSuccessful}{}
-  Returns true if all tests run so far have passed, otherwise returns
+  Returns \constant{True} if all tests run so far have passed,
-  false.
+  otherwise returns \constant{False}.
+\end{methoddesc}
+
+\begin{methoddesc}[TestResult]{stop}{}
+  This method can be called to signal that the set of tests being run
+  should be aborted by setting the \class{TestResult}'s \code{shouldStop}
+  attribute to \constant{True}.  \class{TestRunner} objects should respect
+  this flag and return without running any additional tests.
+  
+  For example, this feature is used by the \class{TextTestRunner} class
+  to stop the test framework when the user signals an interrupt from
+  the keyboard.  Interactive tools which provide \class{TestRunner}
+  implementations can use this in a similar manner.
 \end{methoddesc}
 
 
@@ -786,10 +825,9 @@ reporting while tests are being run.
 \end{methoddesc}
 
 \begin{methoddesc}[TestResult]{addError}{test, err}
-  Called when the test case \var{test} raises an exception without
+  Called when the test case \var{test} raises an unexpected exception
-  signalling a test failure.  \var{err} is a tuple of the form
+  \var{err} is a tuple of the form returned by \function{sys.exc_info()}:
-  returned by \function{sys.exc_info()}:  \code{(\var{type},
+  \code{(\var{type}, \var{value}, \var{traceback})}.
-  \var{value}, \var{traceback})}.
 \end{methoddesc}
 
 \begin{methoddesc}[TestResult]{addFailure}{test, err}
@@ -800,23 +838,10 @@ reporting while tests are being run.
 \end{methoddesc}
 
 \begin{methoddesc}[TestResult]{addSuccess}{test}
-  This method is called for a test that does not fail; \var{test} is
+  Called when the test case \var{test} succeeds.
-  the test case object.
 \end{methoddesc}
 
 
-One additional method is available for \class{TestResult} objects:
-
-\begin{methoddesc}[TestResult]{stop}{}
-  This method can be called to signal that the set of tests being run
-  should be aborted.  Once this has been called, the
-  \class{TestRunner} object return to its caller without running any
-  additional tests.  This is used by the \class{TextTestRunner} class
-  to stop the test framework when the user signals an interrupt from
-  the keyboard.  Interactive tools which provide runners can use this
-  in a similar manner.
-\end{methoddesc}
-
 
 \subsection{TestLoader Objects
             \label{testloader-objects}}
@@ -824,15 +849,15 @@ One additional method is available for \class{TestResult} objects:
 The \class{TestLoader} class is used to create test suites from
 classes and modules.  Normally, there is no need to create an instance
 of this class; the \refmodule{unittest} module provides an instance
-that can be shared as the \code{defaultTestLoader} module attribute.
+that can be shared as \code{unittest.defaultTestLoader}.
-Using a subclass or instance would allow customization of some
+Using a subclass or instance, however, allows customization of some
 configurable properties.
 
 \class{TestLoader} objects have the following methods:
 
 \begin{methoddesc}[TestLoader]{loadTestsFromTestCase}{testCaseClass}
   Return a suite of all tests cases contained in the
-  \class{TestCase}-derived class \class{testCaseClass}.
+  \class{TestCase}-derived \class{testCaseClass}.
 \end{methoddesc}
 
 \begin{methoddesc}[TestLoader]{loadTestsFromModule}{module}
@@ -842,7 +867,7 @@ configurable properties.
   method defined for the class.
 
   \warning{While using a hierarchy of
-  \class{Testcase}-derived classes can be convenient in sharing
+  \class{TestCase}-derived classes can be convenient in sharing
   fixtures and helper functions, defining test methods on base classes
   that are not intended to be instantiated directly does not play well
   with this method.  Doing so, however, can be useful when the
@@ -853,21 +878,23 @@ configurable properties.
   Return a suite of all tests cases given a string specifier.
 
   The specifier \var{name} is a ``dotted name'' that may resolve
-  either to a module, a test case class, a test method within a test
+  either to a module, a test case class, a \class{TestSuite} instance,
-  case class, or a callable object which returns a \class{TestCase} or
+  a test method within a test case class, or a callable object which
-  \class{TestSuite} instance.  For example, if you have a module
+  returns a \class{TestCase} or \class{TestSuite} instance.
-  \module{SampleTests} containing a \class{TestCase}-derived class
+
-  \class{SampleTestCase} with three test methods (\method{test_one()},
+  For example, if you have a module \module{SampleTests} containing a
-  \method{test_two()}, and \method{test_three()}), the specifier
+  \class{TestCase}-derived class \class{SampleTestCase} with three test
-  \code{'SampleTests.SampleTestCase'} would cause this method to
+  methods (\method{test_one()}, \method{test_two()}, and
-  return a suite which will run all three test methods.  Using the
+  \method{test_three()}), the specifier \code{'SampleTests.SampleTestCase'}
-  specifier \code{'SampleTests.SampleTestCase.test_two'} would cause
+  would cause this method to return a suite which will run all three test
-  it to return a test suite which will run only the
+  methods.  Using the specifier \code{'SampleTests.SampleTestCase.test_two'}
+  would cause it to return a test suite which will run only the
   \method{test_two()} test method.  The specifier can refer to modules
   and packages which have not been imported; they will be imported as
   a side-effect.
 
-  The method optionally resolves \var{name} relative to a given module.
+  The method optionally resolves \var{name} relative to the given
+  \var{module}.
 \end{methoddesc}
 
 \begin{methoddesc}[TestLoader]{loadTestsFromNames}{names\optional{, module}}
@@ -888,17 +915,22 @@ either by subclassing or assignment on an instance:
 \begin{memberdesc}[TestLoader]{testMethodPrefix}
   String giving the prefix of method names which will be interpreted
   as test methods.  The default value is \code{'test'}.
+  
+  This affects \method{getTestCaseNames()} and all the
+  \method{loadTestsFrom*()} methods.
 \end{memberdesc}
 
 \begin{memberdesc}[TestLoader]{sortTestMethodsUsing}
   Function to be used to compare method names when sorting them in
-  \method{getTestCaseNames()}.  The default value is the built-in
+  \method{getTestCaseNames()} and all the \method{loadTestsFrom*()} methods.
-  \function{cmp()} function; it can be set to \constant{None} to disable
+  The default value is the built-in \function{cmp()} function; the attribute
-  the sort.
+  can also be set to \constant{None} to disable the sort.
 \end{memberdesc}
 
 \begin{memberdesc}[TestLoader]{suiteClass}
   Callable object that constructs a test suite from a list of tests.
   No methods on the resulting object are needed.  The default value is
   the \class{TestSuite} class.
+  
+  This affects all the \method{loadTestsFrom*()} methods.
 \end{memberdesc}

Misc/NEWS

@@ -49,6 +49,12 @@ Tests
 -----
 
 
+Documentation
+-------------
+
+- Patch #1534922: unittest docs were corrected and enhanced.
+
+
 Build
 -----
 
@@ -433,6 +439,7 @@ Documentation
 
 - Patch #1504046: Add documentation for xml.etree.
 
+
 What's New in Python 2.5 beta 1?
 ================================