Start of documentation for the unittest module. Some of this comes from
Steve Purcell's documentation, and a lot of it is written based on
using PyUnit and reading the implementation.
There is more to come, but I want to get this check in before I have a
disk crash or anything else bad happens.
diff --git a/Doc/lib/libunittest.tex b/Doc/lib/libunittest.tex
new file mode 100644
index 0000000..15787da
--- /dev/null
+++ b/Doc/lib/libunittest.tex
@@ -0,0 +1,266 @@
+\section{\module{unittest} ---
+ Unit testing framework}
+
+\declaremodule{standard}{unittest}
+\moduleauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
+\sectionauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+
+The Python unit testing framework, often 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
+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 three major concepts:
+
+\begin{definitions}
+\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
+base class, \class{TestCase}, which may be used to create new test
+cases.
+
+\term{test suite}
+A \dfn{test suite} is a collection of test cases, test suites, or
+both. It is used to aggregate tests that should be executed
+together.
+
+\term{test runner}
+A \dfn{test runner} is a component which orchestrates the execution of
+tests and provides the outcome to the user. The runner may use a
+graphical interface, a textual interface, or return a special value to
+indicate the results of executing the tests.
+\end{definitions}
+
+
+
+\begin{seealso}
+ \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
+ \module{unittest}.}
+\end{seealso}
+
+
+\subsection{Mapping concepts to classes
+ \label{test-concept-classes}}
+
+
+\subsection{Organizing test code
+ \label{organizing-tests}}
+
+
+\subsection{Re-using old test code
+ \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
+a \class{TestCase} subclass.
+
+For this reason, PyUnit provides a \class{FunctionTestCase} class.
+This subclass of \class{TestCase} can be used to wrap an existing test
+function. Set-up and tear-down functions can also optionally be
+wrapped.
+
+Given the following test function:
+
+\begin{verbatim}
+def testSomething():
+ something = makeSomething()
+ assert something.name is not None
+ # ...
+\end{verbatim}
+
+one can create an equivalent test case instance as follows:
+
+\begin{verbatim}
+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:
+
+\begin{verbatim}
+testcase = unittest.FunctionTestCase(testSomething,
+ setUp=makeSomethingDB,
+ tearDown=deleteSomethingDB)
+\end{verbatim}
+
+
+\subsection{Classes and functions
+ \label{unittest-contents}}
+
+\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
+ as a base class, with specific tests being implemented by concrete
+ subclasses. This class implements the interface needed by the test
+ runner to allow it to drive the test, and methods that the test code
+ can use to check for and report various kinds of failures.
+\end{classdesc}
+
+\begin{classdesc}{FunctionTestCase}{testFunc\optional{,
+ setup\optional{, tearDown\optional{, description}}}}
+ This class implements the portion of the \class{TestCase} interface
+ which allows the test runner to drive the test, but does not provide
+ the methods which test code can use to check and report errors.
+ This is used to create test cases using legacy test code, allowing
+ it to be integrated into a \refmodule{unittest}-based test
+ framework.
+\end{classdesc}
+
+\begin{classdesc}{TestSuite}{}
+ 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
+ contained tests and test suites are executed. Additional methods
+ are provided to add test cases and suites to the aggregation.
+\end{classdesc}
+
+\begin{classdesc}{TestLoader}{}
+\end{classdesc}
+
+\begin{classdesc}{TextTestRunner}{\optional{stream\optional{,
+ descriptions\optional{, verbosity}}}}
+\end{classdesc}
+
+\begin{funcdesc}{main}{\optional{module\optional{,
+ defaultTest\optional{, argv\optional{,
+ 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:
+
+\begin{verbatim}
+if __name__ == '__main__':
+ unittest.main()
+\end{verbatim}
+\end{funcdesc}
+
+
+\subsection{TestCase Objects
+ \label{testcase-objects}}
+
+
+\subsection{TestSuite Objects
+ \label{testsuite-objects}}
+
+\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
+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
+ make up the suite.
+\end{methoddesc}
+
+\begin{methoddesc}[TestSuite]{addTests}{tests}
+ Add all the tests from a sequence of \class{TestCase} and
+ \class{TestSuite} instances to this test suite.
+\end{methoddesc}
+
+
+\subsection{TestResult Objects
+ \label{testresult-objects}}
+
+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
+outcome of tests.
+
+Testing frameworks built on top of \refmodule{unittest} may want
+access to the \class{TestResult} object generated by running a set of
+tests for reporting purposes; a \class{TestResult} instance is
+returned by the \method{TestRunner.run()} method for this purpose.
+
+Each instance holds the total number of tests run, and collections of
+failures and errors that occurred among those test runs. The
+collections contain tuples of \code{(\var{testcase},
+\var{exceptioninfo})}, where \var{exceptioninfo} is a tuple as
+returned by \function{sys.exc_info()}.
+
+\class{TestResult} instances have the following attributes that will
+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
+ \function{sys.exc_info()} results for tests which raised exceptions
+ other than \exception{AssertionError}.
+\end{memberdesc}
+
+\begin{memberdesc}[TestResult]{failures}
+ A list containing pairs of \class{TestCase} instances and the
+ \function{sys.exc_info()} results for tests which raised the
+ \exception{AssertionError} exception.
+\end{memberdesc}
+
+\begin{memberdesc}[TestResult]{testsRun}
+ The number of tests which have been started.
+\end{memberdesc}
+
+\begin{methoddesc}[TestResult]{wasSuccessful}{}
+ Returns true if all tests run so far have passed, otherwise returns
+ false.
+\end{methoddesc}
+
+
+The following methods of the \class{TestResult} class are used to
+maintain the internal data structures, and mmay be extended in
+subclasses to support additional reporting requirements. This is
+particularly useful in building GUI tools which support interactive
+reporting while tests are being run.
+
+\begin{methoddesc}[TestResult]{startTest}{test}
+ Called when the test case \var{test} is about to be run.
+\end{methoddesc}
+
+\begin{methoddesc}[TestResult]{stopTest}{test}
+ Called when the test case \var{test} has been executed, regardless
+ of the outcome.
+\end{methoddesc}
+
+\begin{methoddesc}[TestResult]{addError}{test, err}
+ Called when the test case \var{test} results in an exception other
+ than \exception{AssertionError}. \var{err} is a tuple of the form
+ returned by \function{sys.exc_info()}: \code{(\var{type},
+ \var{value}, \var{traceback})}.
+\end{methoddesc}
+
+\begin{methoddesc}[TestResult]{addFailure}{test, err}
+ Called when the test case \var{test} results in an
+ \exception{AssertionError} exception; the assumption is that the
+ test raised the \exception{AssertionError} and not the
+ implementation being tested. \var{err} is a tuple of the form
+ returned by \function{sys.exc_info()}: \code{(\var{type},
+ \var{value}, \var{traceback})}.
+\end{methoddesc}
+
+\begin{methoddesc}[TestResult]{addSuccess}{test}
+ This method is called for a test that does not fail; \var{test} is
+ 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. GUI tools which provide runners can use this in a
+ similar manner.
+\end{methoddesc}