[Python-checkins] python/dist/src/Doc/lib libunittest.tex,1.13,1.14

rhettinger@users.sourceforge.net rhettinger@users.sourceforge.net
Thu, 10 Jul 2003 15:14:43 -0700


Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv29215

Modified Files:
	libunittest.tex 
Log Message:
SF #767592: unittest docs don't suggest "unittest.main()"

Expanded docs to have a quick start example showing how
to create and run tests.



Index: libunittest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libunittest.tex,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
*** libunittest.tex	10 Feb 2003 19:21:16 -0000	1.13
--- libunittest.tex	10 Jul 2003 22:14:41 -0000	1.14
***************
*** 7,10 ****
--- 7,11 ----
  \sectionauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
  \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+ \sectionauthor{Raymond Hettinger}{python@rcn.com}
  
  \versionadded{2.1}
***************
*** 89,92 ****
--- 90,188 ----
              \module{unittest}.}
  \end{seealso}
+ 
+ 
+ \subsection{Minimal example \label{minimal-example}}
+ 
+ The \module{unittest} module provides a rich set of tools for
+ constructing and running tests.  This section demonstrates that a
+ small subset of the tools suffice to meet the needs of most users.
+ 
+ Here is a short script to test three functions from the
+ \refmodule{random} module:
+ 
+ \begin{verbatim}
+ import random
+ import unittest
+ 
+ class TestSequenceFunctions(unittest.TestCase):
+     
+     def setUp(self):
+         self.seq = range(10)
+ 
+     def testshuffle(self):
+         # make sure the shuffled sequence does not lose any elements
+         random.shuffle(self.seq)
+         self.seq.sort()
+         self.assertEqual(self.seq, range(10))
+ 
+     def testchoice(self):
+         element = random.choice(self.seq)
+         self.assert_(element in self.seq)
+ 
+     def testsample(self):
+         self.assertRaises(ValueError, random.sample, self.seq, 20)
+         for element in random.sample(self.seq, 5):
+             self.assert_(element in self.seq)
+ 
+ if __name__ == '__main__':
+     unittest.main()
+ \end{verbatim}
+ 
+ A testcase is created by subclassing \code{unittest.TestCase}.
+ The three individual tests are defined with methods whose names start with
+ the letters \code{test}.  This naming convention informs the test runner
+ about which methods represent tests.
+ 
+ The crux of each test is a call to \method{assertEqual()} to
+ check for an expected result; \method{assert_()} to verify a condition;
+ or \method{assertRaises()} to verify that an expected exception gets
+ raised.  These methods are used instead of the \keyword{assert} statement
+ so the test runner can accumulate all test results and produce a report.
+ 
+ When a \method{setUp()} method is defined, the test runner will run that
+ method prior to each test.  Likewise, if a \method{tearDown()} method is
+ defined, the test runner will invoke that method after each test.  In the
+ example, \method{setUp()} was used to create a fresh sequence for each test.
+ 
+ The final block shows a simple way to run the tests.  \code{unittest.main()}
+ provides a command line interface to the test script.  When run from the
+ command line, the above script produces an output that looks like this:
+ 
+ \begin{verbatim}
+ ...
+ ----------------------------------------------------------------------
+ Ran 3 tests in 0.000s
+ 
+ OK
+ \end{verbatim}
+ 
+ Instead of \code{unittest.main()}, there are other ways to run the tests
+ with a finer level of control, less terse output, and no requirement to be
+ run from the command line.  For example, the last two lines may be replaced
+ with:
+ 
+ \begin{verbatim}
+ suite = unittest.TestSuite()
+ suite.addTest(unittest.makeSuite(TestSequenceFunctions))
+ unittest.TextTestRunner(verbosity=2).run(suite)
+ \end{verbatim}
+ 
+ Running the revised script from the interpreter or another script
+ produces the following output:
+ 
+ \begin{verbatim}
+ testchoice (__main__.TestSequenceFunctions) ... ok
+ testsample (__main__.TestSequenceFunctions) ... ok
+ testshuffle (__main__.TestSequenceFunctions) ... ok
+ 
+ ----------------------------------------------------------------------
+ Ran 3 tests in 0.110s
+ 
+ OK
+ \end{verbatim}
+ 
+ The above examples show the most commonly used \module{unittest} features
+ which are sufficient to meet many everyday testing needs.  The remainder
+ of the documentation explores the full feature set from first principles.