[Python-checkins] r51675 - python/branches/release25-maint/Doc/lib/libunittest.tex
fred.drake
python-checkins at python.org
Fri Sep 1 05:56:23 CEST 2006
Author: fred.drake
Date: Fri Sep 1 05:56:22 2006
New Revision: 51675
Modified:
python/branches/release25-maint/Doc/lib/libunittest.tex
Log:
- SF patch #1550263: Enhance and correct unittest docs
- various minor cleanups for improved consistency
Modified: python/branches/release25-maint/Doc/lib/libunittest.tex
==============================================================================
--- python/branches/release25-maint/Doc/lib/libunittest.tex (original)
+++ python/branches/release25-maint/Doc/lib/libunittest.tex Fri Sep 1 05:56:22 2006
@@ -212,8 +212,8 @@
class DefaultWidgetSizeTestCase(unittest.TestCase):
def runTest(self):
- widget = Widget("The widget")
- self.failUnless(widget.size() == (50,50), 'incorrect default size')
+ widget = Widget('The widget')
+ self.assertEqual(widget.size(), (50, 50), 'incorrect default size')
\end{verbatim}
Note that in order to test something, we use the one of the
@@ -247,7 +247,7 @@
class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
- self.widget = Widget("The widget")
+ self.widget = Widget('The widget')
class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
def runTest(self):
@@ -273,7 +273,7 @@
class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
- self.widget = Widget("The widget")
+ self.widget = Widget('The widget')
def tearDown(self):
self.widget.dispose()
@@ -298,7 +298,7 @@
class WidgetTestCase(unittest.TestCase):
def setUp(self):
- self.widget = Widget("The widget")
+ self.widget = Widget('The widget')
def tearDown(self):
self.widget.dispose()
@@ -322,8 +322,8 @@
passing the method name in the constructor:
\begin{verbatim}
-defaultSizeTestCase = WidgetTestCase("testDefaultSize")
-resizeTestCase = WidgetTestCase("testResize")
+defaultSizeTestCase = WidgetTestCase('testDefaultSize')
+resizeTestCase = WidgetTestCase('testResize')
\end{verbatim}
Test case instances are grouped together according to the features
@@ -333,8 +333,8 @@
\begin{verbatim}
widgetTestSuite = unittest.TestSuite()
-widgetTestSuite.addTest(WidgetTestCase("testDefaultSize"))
-widgetTestSuite.addTest(WidgetTestCase("testResize"))
+widgetTestSuite.addTest(WidgetTestCase('testDefaultSize'))
+widgetTestSuite.addTest(WidgetTestCase('testResize'))
\end{verbatim}
For the ease of running tests, as we will see later, it is a good
@@ -344,8 +344,8 @@
\begin{verbatim}
def suite():
suite = unittest.TestSuite()
- suite.addTest(WidgetTestCase("testDefaultSize"))
- suite.addTest(WidgetTestCase("testResize"))
+ suite.addTest(WidgetTestCase('testDefaultSize'))
+ suite.addTest(WidgetTestCase('testResize'))
return suite
\end{verbatim}
@@ -353,7 +353,7 @@
\begin{verbatim}
def suite():
- tests = ["testDefaultSize", "testResize"]
+ tests = ['testDefaultSize', 'testResize']
return unittest.TestSuite(map(WidgetTestCase, tests))
\end{verbatim}
@@ -462,7 +462,7 @@
\subsection{Classes and functions
\label{unittest-contents}}
-\begin{classdesc}{TestCase}{}
+\begin{classdesc}{TestCase}{\optional{methodName}}
Instances of the \class{TestCase} class represent the smallest
testable units in the \module{unittest} universe. This class is
intended to be used as a base class, with specific tests being
@@ -470,6 +470,23 @@
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 failure.
+
+ Each instance of \class{TestCase} will run a single test method:
+ the method named \var{methodName}. If you remember, we had an
+ earlier example that went something like this:
+
+ \begin{verbatim}
+ def suite():
+ suite = unittest.TestSuite()
+ suite.addTest(WidgetTestCase('testDefaultSize'))
+ suite.addTest(WidgetTestCase('testResize'))
+ return suite
+ \end{verbatim}
+
+ Here, we create two instances of \class{WidgetTestCase}, each of
+ which runs a single test.
+
+ \var{methodName} defaults to \code{'runTest'}.
\end{classdesc}
\begin{classdesc}{FunctionTestCase}{testFunc\optional{,
@@ -502,6 +519,11 @@
subclass.
\end{classdesc}
+\begin{classdesc}{TestResult}{}
+ This class is used to compile information about which tests have succeeded
+ and which have failed.
+\end{classdesc}
+
\begin{datadesc}{defaultTestLoader}
Instance of the \class{TestLoader} class intended to be shared. If no
customization of the \class{TestLoader} is needed, this instance can
@@ -574,8 +596,9 @@
\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 \constant{None},
- a temporary result object is created and used, but is not made
- available to the caller.
+ a temporary result object is created (by calling the
+ \method{defaultTestCase()} method) and used; this result object is not
+ returned to \method{run()}'s caller.
The same effect may be had by simply calling the \class{TestCase}
instance.
@@ -684,8 +707,13 @@
\end{methoddesc}
\begin{methoddesc}[TestCase]{defaultTestResult}{}
- Return the default type of test result object to be used to run this
- test.
+ Return an instance of the test result class that should be used
+ for this test case class (if no other result instance is provided
+ to the \method{run()} method).
+
+ For \class{TestCase} instances, this will always be an instance of
+ \class{TestResult}; subclasses of \class{TestCase} should
+ override this as necessary.
\end{methoddesc}
\begin{methoddesc}[TestCase]{id}{}
@@ -761,26 +789,20 @@
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{traceback})}, where \var{traceback} is a string containing a
-formatted version of the traceback for the exception.
-
\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 2-tuples of \class{TestCase} instances and
- formatted tracebacks. Each tuple represents a test which raised an
- unexpected exception.
+ strings holding formatted tracebacks. Each tuple represents a test which
+ raised an unexpected exception.
\versionchanged[Contains formatted tracebacks instead of
\function{sys.exc_info()} results]{2.2}
\end{memberdesc}
\begin{memberdesc}[TestResult]{failures}
- A list containing 2-tuples of \class{TestCase} instances and
- formatted tracebacks. Each tuple represents a test where a failure
+ A list containing 2-tuples of \class{TestCase} instances and strings
+ holding formatted tracebacks. Each tuple represents a test where a failure
was explicitly signalled using the \method{TestCase.fail*()} or
\method{TestCase.assert*()} methods.
\versionchanged[Contains formatted tracebacks instead of
@@ -817,17 +839,25 @@
\begin{methoddesc}[TestResult]{startTest}{test}
Called when the test case \var{test} is about to be run.
+
+ The default implementation simply increments the instance's
+ \code{testsRun} counter.
\end{methoddesc}
\begin{methoddesc}[TestResult]{stopTest}{test}
- Called when the test case \var{test} has been executed, regardless
+ Called after the test case \var{test} has been executed, regardless
of the outcome.
+
+ The default implementation does nothing.
\end{methoddesc}
\begin{methoddesc}[TestResult]{addError}{test, err}
Called when the test case \var{test} raises an unexpected exception
\var{err} is a tuple of the form returned by \function{sys.exc_info()}:
\code{(\var{type}, \var{value}, \var{traceback})}.
+
+ The default implementation appends \code{(\var{test}, \var{err})} to
+ the instance's \code{errors} attribute.
\end{methoddesc}
\begin{methoddesc}[TestResult]{addFailure}{test, err}
@@ -835,10 +865,15 @@
\var{err} is a tuple of the form returned by
\function{sys.exc_info()}: \code{(\var{type}, \var{value},
\var{traceback})}.
+
+ The default implementation appends \code{(\var{test}, \var{err})} to
+ the instance's \code{failures} attribute.
\end{methoddesc}
\begin{methoddesc}[TestResult]{addSuccess}{test}
Called when the test case \var{test} succeeds.
+
+ The default implementation does nothing.
\end{methoddesc}
@@ -878,9 +913,12 @@
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 \class{TestSuite} instance,
- a test method within a test case class, or a callable object which
- returns a \class{TestCase} or \class{TestSuite} instance.
+ either to a module, a test case class, a test method within a test
+ case class, a \class{TestSuite} instance, or a callable object which
+ returns a \class{TestCase} or \class{TestSuite} instance. These checks
+ are applied in the order listed here; that is, a method on a possible
+ test case class will be picked up as ``a test method within a test
+ case class'', rather than ``a callable object''.
For example, if you have a module \module{SampleTests} containing a
\class{TestCase}-derived class \class{SampleTestCase} with three test
@@ -905,7 +943,7 @@
\begin{methoddesc}[TestLoader]{getTestCaseNames}{testCaseClass}
Return a sorted sequence of method names found within
- \var{testCaseClass}.
+ \var{testCaseClass}; this should be a subclass of \class{TestCase}.
\end{methoddesc}
More information about the Python-checkins
mailing list