[Python-checkins] CVS: python/dist/src/Doc/lib libunittest.tex,1.3,1.4
Fred L. Drake
fdrake@users.sourceforge.net
Thu, 12 Apr 2001 12:34:40 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv30066
Modified Files:
libunittest.tex
Log Message:
Added module synopsis for the chapter summary.
Added documentation for TestCase.assertRaises().
Added text for "Mapping concepts to classes", and merged it into the
front matter instead of separating it into a new section.
Removed use of "assert" in examples.
Update the descriptions to reflect further changes from discussions on
the pyunit-interest list.
Added documentation for the defaultTestLoader object and the
TestLoader methods.
Added the assert*() names for the TestCase helper methods.
Index: libunittest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libunittest.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -r1.3 -r1.4
*** libunittest.tex 2001/04/12 04:50:06 1.3
--- libunittest.tex 2001/04/12 19:34:38 1.4
***************
*** 3,6 ****
--- 3,7 ----
\declaremodule{standard}{unittest}
+ \modulesynopsis{Unit testing framework for Python.}
\moduleauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
\sectionauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
***************
*** 20,24 ****
set of tests.
! To achieve this, PyUnit supports three major concepts:
\begin{definitions}
--- 21,25 ----
set of tests.
! To achieve this, PyUnit supports some important concepts:
\begin{definitions}
***************
*** 48,52 ****
--- 49,83 ----
+ 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 later can be used when
+ integrating existing test code with a PyUnit-driven framework. 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
+ constructor for these purposes. When the test is run, the
+ fixture initialization is run first; if it succeeds, the cleanup
+ method is run after the test has been executed, regardless of the
+ outcome of the test. Each instance of the \class{TestCase} will only
+ be used to run a single test method, so a new fixture is created for
+ each test.
+
+ Test suites are implemented by the \class{TestSuite} class. This
+ class allows individual tests and test suites to be aggregated; when
+ the suite is executed, all tests added directly to the suite and in
+ ``child'' test suites are run.
+
+ 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
+ provide the \class{TextTestRunner} as an example test runner which
+ reports test results on the standard error stream by default.
+ Alternate runners can be implemented for other environments (such as
+ graphical environments) without any need to derive from a specific
+ class.
+
\begin{seealso}
\seetitle[http://pyunit.sourceforge.net/]{PyUnit Web Site}{The
***************
*** 59,66 ****
- \subsection{Mapping concepts to classes
- \label{test-concept-classes}}
-
-
\subsection{Organizing test code
\label{organizing-tests}}
--- 90,93 ----
***************
*** 90,102 ****
def runTest(self):
widget = Widget("The widget")
! assert widget.size() == (50,50), 'incorrect default size'
\end{verbatim}
! Note that in order to test something, we just use the built-in 'assert'
! statement of Python. If the test fails when the test case runs,
! \class{TestFailed} will be raised, and the testing framework
! will identify the test case as a \dfn{failure}. Other exceptions that
! do not arise from explicit 'assert' checks are identified by the testing
! framework as dfn{errors}.
The way to run a test case will be described later. For now, note
--- 117,131 ----
def runTest(self):
widget = Widget("The widget")
! self.failUnless(widget.size() == (50,50), 'incorrect default size')
\end{verbatim}
! 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
! runs, an exception will be raised, and the testing framework will
! identify the test case as a \dfn{failure}. Other exceptions that do
! not arise from checks made through the \method{assert*()} and
! \method{fail*()} methods are identified by the testing framework as
! dfn{errors}.
The way to run a test case will be described later. For now, note
***************
*** 125,135 ****
class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
def runTest(self):
! assert self.widget.size() == (50,50), 'incorrect default size'
class WidgetResizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.widget.resize(100,150)
! assert self.widget.size() == (100,150), \
! 'wrong size after resize'
\end{verbatim}
--- 154,165 ----
class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
def runTest(self):
! self.failUnless(self.widget.size() == (50,50),
! 'incorrect default size')
class WidgetResizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.widget.resize(100,150)
! self.failUnless(self.widget.size() == (100,150),
! 'wrong size after resize')
\end{verbatim}
***************
*** 178,188 ****
def testDefaultSize(self):
! assert self.widget.size() == (50,50), \
! 'incorrect default size'
def testResize(self):
self.widget.resize(100,150)
! assert self.widget.size() == (100,150), \
! 'wrong size after resize'
\end{verbatim}
--- 208,218 ----
def testDefaultSize(self):
! self.failUnless(self.widget.size() == (50,50),
! 'incorrect default size')
def testResize(self):
self.widget.resize(100,150)
! self.failUnless(self.widget.size() == (100,150),
! 'wrong size after resize')
\end{verbatim}
***************
*** 316,320 ****
\end{verbatim}
-
\strong{Note:} PyUnit supports the use of \exception{AssertionError}
as an indicator of test failure, but does not recommend it. Future
--- 346,349 ----
***************
*** 335,339 ****
\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
--- 364,368 ----
\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
***************
*** 364,367 ****
--- 393,402 ----
\end{classdesc}
+ \begin{datadesc}{defaultTestLoader}
+ Instance of the \class{TestLoader} class which can be shared. If no
+ customization of the \class{TestLoader} is needed, this instance can
+ always be used instead of creating new instances.
+ \end{datadesc}
+
\begin{classdesc}{TextTestRunner}{\optional{stream\optional{,
descriptions\optional{, verbosity}}}}
***************
*** 385,394 ****
\end{funcdesc}
- \begin{excdesc}{TestFailed}
- Exception raised to indicate that a test failed. The
- \method{TestCase.fail()} method is responsible for creating and
- raising this exception.
- \end{excdesc}
-
\subsection{TestCase Objects
--- 420,423 ----
***************
*** 414,425 ****
\end{methoddesc}
- \begin{methoddesc}[TestCase]{run}{\optional{result}}
- Run the test, collecting the result into the test result object
- passed as \var{result}. If \var{result} is omitted or \code{None},
- a temporary result object is created and used, but is not made
- available to the caller. This is equivalent to simply calling the
- \class{TestCase} instance.
- \end{methoddesc}
-
\begin{methoddesc}[TestCase]{tearDown}{}
Method called immediately after the test method has been called and
--- 443,446 ----
***************
*** 428,434 ****
particularly careful about checking internal state. Any exception
raised by this method will be considered an error rather than a test
! failure. The default implementation does nothing.
\end{methoddesc}
\begin{methoddesc}[TestCase]{debug}{}
Run the test without collecting the result. This allows exceptions
--- 449,465 ----
particularly careful about checking internal state. Any exception
raised by this method will be considered an error rather than a test
! failure. This method will only be called if the \method{setUp()}
! succeeds, regardless of the outcome of the test method.
! The default implementation does nothing.
\end{methoddesc}
+ \begin{methoddesc}[TestCase]{run}{\optional{result}}
+ Run the test, collecting the result into the test result object
+ passed as \var{result}. If \var{result} is omitted or \code{None},
+ a temporary result object is created and used, but is not made
+ available to the caller. This is equivalent to simply calling the
+ \class{TestCase} instance.
+ \end{methoddesc}
+
\begin{methoddesc}[TestCase]{debug}{}
Run the test without collecting the result. This allows exceptions
***************
*** 439,465 ****
The test code can use any of the following methods to check for and
! report failures:
! \begin{methoddesc}[TestCase]{failUnless}{expr\optional{, msg}}
! This method is similar to the \keyword{assert} statement, except it
! works even when Python is executed in ``optimizing'' mode (using the
! \programopt{-O} command line switch), and raises the
! \exception{TestFailed} exception. If \var{expr} is false,
! \exception{TestFailed} will be raised with \var{msg} as the
! message describing the failure; \code{None} will be used for the
! message if \var{msg} is omitted.
\end{methoddesc}
! \begin{methoddesc}[TestCase]{failUnlessEqual}{first, second\optional{, msg}}
Test that \var{first} and \var{second} are equal. If the values do
not compare equal, the test will fail with the explanation given by
\var{msg}, or \code{None}. Note that using \method{failUnlessEqual()}
improves upon doing the comparison as the first parameter to
! \method{failUnless()} is that the default value for \var{msg} can be
computed to include representations of both \var{first} and
\var{second}.
\end{methoddesc}
! \begin{methoddesc}[TestCase]{failIfEqual}{first, second\optional{, msg}}
Test that \var{first} and \var{second} are not equal. If the values
do compare equal, the test will fail with the explanation given by
--- 470,495 ----
The test code can use any of the following methods to check for and
! report failures.
! \begin{methoddesc}[TestCase]{assert_}{expr\optional{, msg}}
! \methodline{failUnless}{expr\optional{, msg}}
! Signal a test failure if \var{expr} is false; the explanation for
! the error will be \var{msg} if given, otherwise it will be
! \code{None}.
\end{methoddesc}
! \begin{methoddesc}[TestCase]{assertEqual}{first, second\optional{, msg}}
! \methodline{failUnlessEqual}{first, second\optional{, msg}}
Test that \var{first} and \var{second} are equal. If the values do
not compare equal, the test will fail with the explanation given by
\var{msg}, or \code{None}. Note that using \method{failUnlessEqual()}
improves upon doing the comparison as the first parameter to
! \method{failUnless()}: the default value for \var{msg} can be
computed to include representations of both \var{first} and
\var{second}.
\end{methoddesc}
! \begin{methoddesc}[TestCase]{assertNotEqual}{first, second\optional{, msg}}
! \methodline{failIfEqual}{first, second\optional{, msg}}
Test that \var{first} and \var{second} are not equal. If the values
do compare equal, the test will fail with the explanation given by
***************
*** 471,486 ****
\end{methoddesc}
\begin{methoddesc}[TestCase]{failIf}{expr\optional{, msg}}
The inverse of the \method{failUnless()} method is the
! \method{failIf()} method. This raises \exception{TestFailed} if
! \var{expr} is true, with \var{msg} or \code{None} for the error
! message.
\end{methoddesc}
\begin{methoddesc}[TestCase]{fail}{\optional{msg}}
! Fail unconditionally, with \var{msg} or \code{None} for the error
! message.
\end{methoddesc}
Testing frameworks can use the following methods to collect
--- 501,534 ----
\end{methoddesc}
+ \begin{methoddesc}[TestCase]{assertRaises}{exception, callable, \moreargs}
+ \methodline{failUnlessRaises}{exception, callable, \moreargs}
+ Test that an exception is raised when \var{callable} is called with
+ any positional or keyword arguments that are also passed to
+ \method{assertRaises()}. The test passes if \var{exception} is
+ raised, is an error if another exception is raised, or fails if no
+ exception is raised. To catch any of a group of exceptions, a tuple
+ containing the exception classes may be passed as \var{exception}.
+ \end{methoddesc}
+
\begin{methoddesc}[TestCase]{failIf}{expr\optional{, msg}}
The inverse of the \method{failUnless()} method is the
! \method{failIf()} method. This signals a test failure if \var{expr}
! is true, with \var{msg} or \code{None} for the error message.
\end{methoddesc}
\begin{methoddesc}[TestCase]{fail}{\optional{msg}}
! Signals a test failure unconditionally, with \var{msg} or
! \code{None} for the error message.
\end{methoddesc}
+ \begin{memberdesc}[TestCase]{failureException}
+ This class attribute gives the exception raised by the
+ \method{test()} method. If a test framework needs to use a
+ specialized exception, possibly to carry additional information, it
+ must subclass this exception in order to ``play fair'' with the
+ framework. The initial value of this attribute is
+ \exception{AssertionError}.
+ \end{memberdesc}
+
Testing frameworks can use the following methods to collect
***************
*** 557,568 ****
\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} and \exception{TestFailed}.
\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 either
! \exception{TestFailed} or \exception{AssertionError}.
\end{memberdesc}
--- 605,616 ----
\begin{memberdesc}[TestResult]{errors}
A list containing pairs of \class{TestCase} instances and the
! \function{sys.exc_info()} results for tests which raised an
! exception but did not signal a test failure.
\end{memberdesc}
\begin{memberdesc}[TestResult]{failures}
A list containing pairs of \class{TestCase} instances and the
! \function{sys.exc_info()} results for tests which signalled a
! failure in the code under test.
\end{memberdesc}
***************
*** 593,608 ****
\begin{methoddesc}[TestResult]{addError}{test, err}
! Called when the test case \var{test} results in an exception other
! than \exception{TestFailed} or \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 either \exception{TestFailed} or
! \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},
--- 641,652 ----
\begin{methoddesc}[TestResult]{addError}{test, err}
! Called when the test case \var{test} raises an exception without
! signalling a test failure. \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} signals a failure.
\var{err} is a tuple of the form returned by
\function{sys.exc_info()}: \code{(\var{type}, \var{value},
***************
*** 627,628 ****
--- 671,747 ----
similar manner.
\end{methoddesc}
+
+
+ \subsection{TestLoader Objects
+ \label{testloader-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.
+ Using a subclass or instance would allow 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}.
+ \end{methoddesc}
+
+ \begin{methoddesc}[TestLoader]{loadTestsFromModule}{module}
+ Return a suite of all tests cases contained in the given module.
+ This method searches \var{module} for classes derived from
+ \class{TestCase} and creates an instance of the class for each test
+ method defined for the class.
+
+ \strong{Warning:} While using a hierarchy of
+ \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
+ fixtures are different and defined in subclasses.
+ \end{methoddesc}
+
+ \begin{methoddesc}[TestLoader]{loadTestsFromName}{name\optional{, module}}
+ Return a suite of all tests cases given a string specifier.
+
+ The specifier \var{name} may resolve either to a module, a test case
+ class, a test method within a test case class, or a callable object
+ which returns a \class{TestCase} or \class{TestSuite} instance.
+
+ The method optionally resolves \var{name} relative to a given module.
+ \end{methoddesc}
+
+ \begin{methoddesc}[TestLoader]{loadTestsFromNames}{names\optional{, module}}
+ Similar to \method{loadTestsFromName()}, but takes a sequence of
+ names rather than a single name. The return value is a test suite
+ which supports all the tests defined for each name.
+ \end{methoddesc}
+
+ \begin{methoddesc}[TestLoader]{getTestCaseNames}{testCaseClass}
+ Return a sorted sequence of method names found within
+ \var{testCaseClass}.
+ \end{methoddesc}
+
+
+ The following attributes of a \class{TestLoader} can be configured
+ 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'}.
+ \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
+ \function{cmp()} function; it can be set to \code{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.
+ \end{memberdesc}