Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 1 | \section{\module{unittest} --- |
| 2 | Unit testing framework} |
| 3 | |
| 4 | \declaremodule{standard}{unittest} |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 5 | \modulesynopsis{Unit testing framework for Python.} |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 6 | \moduleauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com} |
| 7 | \sectionauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com} |
| 8 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 9 | |
Fred Drake | 5430f4e | 2002-10-10 16:16:25 +0000 | [diff] [blame] | 10 | \versionadded{2.1} |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 11 | |
| 12 | The Python unit testing framework, often referred to as ``PyUnit,'' is |
| 13 | a Python language version of JUnit, by Kent Beck and Erich Gamma. |
| 14 | JUnit is, in turn, a Java version of Kent's Smalltalk testing |
| 15 | framework. Each is the de facto standard unit testing framework for |
| 16 | its respective language. |
| 17 | |
| 18 | PyUnit supports test automation, sharing of setup and shutdown code |
| 19 | for tests, aggregation of tests into collections, and independence of |
| 20 | the tests from the reporting framework. The \module{unittest} module |
| 21 | provides classes that make it easy to support these qualities for a |
| 22 | set of tests. |
| 23 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 24 | To achieve this, PyUnit supports some important concepts: |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 25 | |
| 26 | \begin{definitions} |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 27 | \term{test fixture} |
| 28 | A \dfn{test fixture} represents the preparation needed to perform one |
| 29 | or more tests, and any associate cleanup actions. This may involve, |
| 30 | for example, creating temporary or proxy databases, directories, or |
| 31 | starting a server process. |
| 32 | |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 33 | \term{test case} |
| 34 | A \dfn{test case} is the smallest unit of testing. It checks for a |
| 35 | specific response to a particular set of inputs. PyUnit provides a |
| 36 | base class, \class{TestCase}, which may be used to create new test |
| 37 | cases. |
| 38 | |
| 39 | \term{test suite} |
| 40 | A \dfn{test suite} is a collection of test cases, test suites, or |
| 41 | both. It is used to aggregate tests that should be executed |
| 42 | together. |
| 43 | |
| 44 | \term{test runner} |
| 45 | A \dfn{test runner} is a component which orchestrates the execution of |
| 46 | tests and provides the outcome to the user. The runner may use a |
| 47 | graphical interface, a textual interface, or return a special value to |
| 48 | indicate the results of executing the tests. |
| 49 | \end{definitions} |
| 50 | |
| 51 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 52 | The test case and test fixture concepts are supported through the |
| 53 | \class{TestCase} and \class{FunctionTestCase} classes; the former |
Just van Rossum | edd179e | 2002-12-15 13:14:22 +0000 | [diff] [blame] | 54 | should be used when creating new tests, and the latter can be used when |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 55 | integrating existing test code with a PyUnit-driven framework. When |
| 56 | building test fixtures using \class{TestCase}, the \method{setUp()} |
| 57 | and \method{tearDown()} methods can be overridden to provide |
| 58 | initialization and cleanup for the fixture. With |
| 59 | \class{FunctionTestCase}, existing functions can be passed to the |
| 60 | constructor for these purposes. When the test is run, the |
| 61 | fixture initialization is run first; if it succeeds, the cleanup |
| 62 | method is run after the test has been executed, regardless of the |
| 63 | outcome of the test. Each instance of the \class{TestCase} will only |
| 64 | be used to run a single test method, so a new fixture is created for |
| 65 | each test. |
| 66 | |
| 67 | Test suites are implemented by the \class{TestSuite} class. This |
| 68 | class allows individual tests and test suites to be aggregated; when |
| 69 | the suite is executed, all tests added directly to the suite and in |
| 70 | ``child'' test suites are run. |
| 71 | |
| 72 | A test runner is an object that provides a single method, |
| 73 | \method{run()}, which accepts a \class{TestCase} or \class{TestSuite} |
| 74 | object as a parameter, and returns a result object. The class |
| 75 | \class{TestResult} is provided for use as the result object. PyUnit |
| 76 | provide the \class{TextTestRunner} as an example test runner which |
| 77 | reports test results on the standard error stream by default. |
| 78 | Alternate runners can be implemented for other environments (such as |
| 79 | graphical environments) without any need to derive from a specific |
| 80 | class. |
| 81 | |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 82 | |
| 83 | \begin{seealso} |
| 84 | \seetitle[http://pyunit.sourceforge.net/]{PyUnit Web Site}{The |
| 85 | source for further information on PyUnit.} |
| 86 | \seetitle[http://www.XProgramming.com/testfram.htm]{Simple Smalltalk |
| 87 | Testing: With Patterns}{Kent Beck's original paper on |
| 88 | testing frameworks using the pattern shared by |
| 89 | \module{unittest}.} |
| 90 | \end{seealso} |
| 91 | |
| 92 | |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 93 | \subsection{Organizing test code |
| 94 | \label{organizing-tests}} |
| 95 | |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 96 | The basic building blocks of unit testing are \dfn{test cases} --- |
| 97 | single scenarios that must be set up and checked for correctness. In |
| 98 | PyUnit, test cases are represented by instances of the |
| 99 | \class{TestCase} class in the \refmodule{unittest} module. To make |
| 100 | your own test cases you must write subclasses of \class{TestCase}, or |
| 101 | use \class{FunctionTestCase}. |
| 102 | |
| 103 | An instance of a \class{TestCase}-derived class is an object that can |
| 104 | completely run a single test method, together with optional set-up |
| 105 | and tidy-up code. |
| 106 | |
| 107 | The testing code of a \class{TestCase} instance should be entirely |
| 108 | self contained, such that it can be run either in isolation or in |
| 109 | arbitrary combination with any number of other test cases. |
| 110 | |
| 111 | The simplest test case subclass will simply override the |
| 112 | \method{runTest()} method in order to perform specific testing code: |
| 113 | |
| 114 | \begin{verbatim} |
| 115 | import unittest |
| 116 | |
| 117 | class DefaultWidgetSizeTestCase(unittest.TestCase): |
| 118 | def runTest(self): |
| 119 | widget = Widget("The widget") |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 120 | self.failUnless(widget.size() == (50,50), 'incorrect default size') |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 121 | \end{verbatim} |
| 122 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 123 | Note that in order to test something, we use the one of the |
| 124 | \method{assert*()} or \method{fail*()} methods provided by the |
| 125 | \class{TestCase} base class. If the test fails when the test case |
| 126 | runs, an exception will be raised, and the testing framework will |
| 127 | identify the test case as a \dfn{failure}. Other exceptions that do |
| 128 | not arise from checks made through the \method{assert*()} and |
| 129 | \method{fail*()} methods are identified by the testing framework as |
| 130 | dfn{errors}. |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 131 | |
| 132 | The way to run a test case will be described later. For now, note |
| 133 | that to construct an instance of such a test case, we call its |
| 134 | constructor without arguments: |
| 135 | |
| 136 | \begin{verbatim} |
| 137 | testCase = DefaultWidgetSizeTestCase() |
| 138 | \end{verbatim} |
| 139 | |
| 140 | Now, such test cases can be numerous, and their set-up can be |
| 141 | repetitive. In the above case, constructing a ``Widget'' in each of |
| 142 | 100 Widget test case subclasses would mean unsightly duplication. |
| 143 | |
| 144 | Luckily, we can factor out such set-up code by implementing a method |
| 145 | called \method{setUp()}, which the testing framework will |
| 146 | automatically call for us when we run the test: |
| 147 | |
| 148 | \begin{verbatim} |
| 149 | import unittest |
| 150 | |
| 151 | class SimpleWidgetTestCase(unittest.TestCase): |
| 152 | def setUp(self): |
| 153 | self.widget = Widget("The widget") |
| 154 | |
| 155 | class DefaultWidgetSizeTestCase(SimpleWidgetTestCase): |
| 156 | def runTest(self): |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 157 | self.failUnless(self.widget.size() == (50,50), |
| 158 | 'incorrect default size') |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 159 | |
| 160 | class WidgetResizeTestCase(SimpleWidgetTestCase): |
| 161 | def runTest(self): |
| 162 | self.widget.resize(100,150) |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 163 | self.failUnless(self.widget.size() == (100,150), |
| 164 | 'wrong size after resize') |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 165 | \end{verbatim} |
| 166 | |
| 167 | If the \method{setUp()} method raises an exception while the test is |
| 168 | running, the framework will consider the test to have suffered an |
| 169 | error, and the \method{runTest()} method will not be executed. |
| 170 | |
| 171 | Similarly, we can provide a \method{tearDown()} method that tidies up |
| 172 | after the \method{runTest()} method has been run: |
| 173 | |
| 174 | \begin{verbatim} |
| 175 | import unittest |
| 176 | |
| 177 | class SimpleWidgetTestCase(unittest.TestCase): |
| 178 | def setUp(self): |
| 179 | self.widget = Widget("The widget") |
| 180 | |
| 181 | def tearDown(self): |
| 182 | self.widget.dispose() |
| 183 | self.widget = None |
| 184 | \end{verbatim} |
| 185 | |
| 186 | If \method{setUp()} succeeded, the \method{tearDown()} method will be |
| 187 | run regardless of whether or not \method{runTest()} succeeded. |
| 188 | |
| 189 | Such a working environment for the testing code is called a |
| 190 | \dfn{fixture}. |
| 191 | |
| 192 | Often, many small test cases will use the same fixture. In this case, |
| 193 | we would end up subclassing \class{SimpleWidgetTestCase} into many |
| 194 | small one-method classes such as |
| 195 | \class{DefaultWidgetSizeTestCase}. This is time-consuming and |
| 196 | discouraging, so in the same vein as JUnit, PyUnit provides a simpler |
| 197 | mechanism: |
| 198 | |
| 199 | \begin{verbatim} |
| 200 | import unittest |
| 201 | |
| 202 | class WidgetTestCase(unittest.TestCase): |
| 203 | def setUp(self): |
| 204 | self.widget = Widget("The widget") |
| 205 | |
| 206 | def tearDown(self): |
| 207 | self.widget.dispose() |
| 208 | self.widget = None |
| 209 | |
| 210 | def testDefaultSize(self): |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 211 | self.failUnless(self.widget.size() == (50,50), |
| 212 | 'incorrect default size') |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 213 | |
| 214 | def testResize(self): |
| 215 | self.widget.resize(100,150) |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 216 | self.failUnless(self.widget.size() == (100,150), |
| 217 | 'wrong size after resize') |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 218 | \end{verbatim} |
| 219 | |
| 220 | Here we have not provided a \method{runTest()} method, but have |
| 221 | instead provided two different test methods. Class instances will now |
| 222 | each run one of the \method{test*()} methods, with \code{self.widget} |
| 223 | created and destroyed separately for each instance. When creating an |
| 224 | instance we must specify the test method it is to run. We do this by |
| 225 | passing the method name in the constructor: |
| 226 | |
| 227 | \begin{verbatim} |
| 228 | defaultSizeTestCase = WidgetTestCase("testDefaultSize") |
| 229 | resizeTestCase = WidgetTestCase("testResize") |
| 230 | \end{verbatim} |
| 231 | |
| 232 | Test case instances are grouped together according to the features |
| 233 | they test. PyUnit provides a mechanism for this: the \class{test |
| 234 | suite}, represented by the class \class{TestSuite} in the |
| 235 | \refmodule{unittest} module: |
| 236 | |
| 237 | \begin{verbatim} |
| 238 | widgetTestSuite = unittest.TestSuite() |
| 239 | widgetTestSuite.addTest(WidgetTestCase("testDefaultSize")) |
| 240 | widgetTestSuite.addTest(WidgetTestCase("testResize")) |
| 241 | \end{verbatim} |
| 242 | |
| 243 | For the ease of running tests, as we will see later, it is a good |
| 244 | idea to provide in each test module a callable object that returns a |
| 245 | pre-built test suite: |
| 246 | |
| 247 | \begin{verbatim} |
| 248 | def suite(): |
| 249 | suite = unittest.TestSuite() |
| 250 | suite.addTest(WidgetTestCase("testDefaultSize")) |
| 251 | suite.addTest(WidgetTestCase("testResize")) |
| 252 | return suite |
| 253 | \end{verbatim} |
| 254 | |
| 255 | or even: |
| 256 | |
| 257 | \begin{verbatim} |
| 258 | class WidgetTestSuite(unittest.TestSuite): |
| 259 | def __init__(self): |
| 260 | unittest.TestSuite.__init__(self,map(WidgetTestCase, |
| 261 | ("testDefaultSize", |
| 262 | "testResize"))) |
| 263 | \end{verbatim} |
| 264 | |
| 265 | (The latter is admittedly not for the faint-hearted!) |
| 266 | |
| 267 | Since it is a common pattern to create a \class{TestCase} subclass |
| 268 | with many similarly named test functions, there is a convenience |
| 269 | function called \function{makeSuite()} provided in the |
| 270 | \refmodule{unittest} module that constructs a test suite that |
| 271 | comprises all of the test cases in a test case class: |
| 272 | |
| 273 | \begin{verbatim} |
| 274 | suite = unittest.makeSuite(WidgetTestCase,'test') |
| 275 | \end{verbatim} |
| 276 | |
| 277 | Note that when using the \function{makeSuite()} function, the order in |
| 278 | which the various test cases will be run by the test suite is the |
| 279 | order determined by sorting the test function names using the |
| 280 | \function{cmp()} built-in function. |
| 281 | |
| 282 | Often it is desirable to group suites of test cases together, so as to |
| 283 | run tests for the whole system at once. This is easy, since |
| 284 | \class{TestSuite} instances can be added to a \class{TestSuite} just |
| 285 | as \class{TestCase} instances can be added to a \class{TestSuite}: |
| 286 | |
| 287 | \begin{verbatim} |
| 288 | suite1 = module1.TheTestSuite() |
| 289 | suite2 = module2.TheTestSuite() |
| 290 | alltests = unittest.TestSuite((suite1, suite2)) |
| 291 | \end{verbatim} |
| 292 | |
| 293 | You can place the definitions of test cases and test suites in the |
| 294 | same modules as the code they are to test (e.g.\ \file{widget.py}), |
| 295 | but there are several advantages to placing the test code in a |
| 296 | separate module, such as \file{widgettests.py}: |
| 297 | |
| 298 | \begin{itemize} |
| 299 | \item The test module can be run standalone from the command line. |
| 300 | \item The test code can more easily be separated from shipped code. |
Michael W. Hudson | aab0260 | 2003-02-10 19:21:16 +0000 | [diff] [blame^] | 301 | \item There is less temptation to change test code to fit the code |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 302 | it tests without a good reason. |
| 303 | \item Test code should be modified much less frequently than the |
| 304 | code it tests. |
| 305 | \item Tested code can be refactored more easily. |
| 306 | \item Tests for modules written in C must be in separate modules |
| 307 | anyway, so why not be consistent? |
| 308 | \item If the testing strategy changes, there is no need to change |
| 309 | the source code. |
| 310 | \end{itemize} |
| 311 | |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 312 | |
| 313 | \subsection{Re-using old test code |
| 314 | \label{legacy-unit-tests}} |
| 315 | |
| 316 | Some users will find that they have existing test code that they would |
| 317 | like to run from PyUnit, without converting every old test function to |
| 318 | a \class{TestCase} subclass. |
| 319 | |
| 320 | For this reason, PyUnit provides a \class{FunctionTestCase} class. |
| 321 | This subclass of \class{TestCase} can be used to wrap an existing test |
| 322 | function. Set-up and tear-down functions can also optionally be |
| 323 | wrapped. |
| 324 | |
| 325 | Given the following test function: |
| 326 | |
| 327 | \begin{verbatim} |
| 328 | def testSomething(): |
| 329 | something = makeSomething() |
| 330 | assert something.name is not None |
| 331 | # ... |
| 332 | \end{verbatim} |
| 333 | |
| 334 | one can create an equivalent test case instance as follows: |
| 335 | |
| 336 | \begin{verbatim} |
| 337 | testcase = unittest.FunctionTestCase(testSomething) |
| 338 | \end{verbatim} |
| 339 | |
| 340 | If there are additional set-up and tear-down methods that should be |
| 341 | called as part of the test case's operation, they can also be provided: |
| 342 | |
| 343 | \begin{verbatim} |
| 344 | testcase = unittest.FunctionTestCase(testSomething, |
| 345 | setUp=makeSomethingDB, |
| 346 | tearDown=deleteSomethingDB) |
| 347 | \end{verbatim} |
| 348 | |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 349 | \note{PyUnit supports the use of \exception{AssertionError} |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 350 | as an indicator of test failure, but does not recommend it. Future |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 351 | versions may treat \exception{AssertionError} differently.} |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 352 | |
| 353 | |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 354 | \subsection{Classes and functions |
| 355 | \label{unittest-contents}} |
| 356 | |
| 357 | \begin{classdesc}{TestCase}{} |
| 358 | Instances of the \class{TestCase} class represent the smallest |
| 359 | testable units in a set of tests. This class is intended to be used |
| 360 | as a base class, with specific tests being implemented by concrete |
| 361 | subclasses. This class implements the interface needed by the test |
| 362 | runner to allow it to drive the test, and methods that the test code |
| 363 | can use to check for and report various kinds of failures. |
| 364 | \end{classdesc} |
| 365 | |
| 366 | \begin{classdesc}{FunctionTestCase}{testFunc\optional{, |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 367 | setUp\optional{, tearDown\optional{, description}}}} |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 368 | This class implements the portion of the \class{TestCase} interface |
| 369 | which allows the test runner to drive the test, but does not provide |
| 370 | the methods which test code can use to check and report errors. |
| 371 | This is used to create test cases using legacy test code, allowing |
| 372 | it to be integrated into a \refmodule{unittest}-based test |
| 373 | framework. |
| 374 | \end{classdesc} |
| 375 | |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 376 | \begin{classdesc}{TestSuite}{\optional{tests}} |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 377 | This class represents an aggregation of individual tests cases and |
| 378 | test suites. The class presents the interface needed by the test |
| 379 | runner to allow it to be run as any other test case, but all the |
| 380 | contained tests and test suites are executed. Additional methods |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 381 | are provided to add test cases and suites to the aggregation. If |
| 382 | \var{tests} is given, it must be a sequence of individual tests that |
| 383 | will be added to the suite. |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 384 | \end{classdesc} |
| 385 | |
| 386 | \begin{classdesc}{TestLoader}{} |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 387 | This class is responsible for loading tests according to various |
| 388 | criteria and returning them wrapped in a \class{TestSuite}. |
| 389 | It can load all tests within a given module or \class{TestCase} |
| 390 | class. When loading from a module, it considers all |
| 391 | \class{TestCase}-derived classes. For each such class, it creates |
| 392 | an instance for each method with a name beginning with the string |
| 393 | \samp{test}. |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 394 | \end{classdesc} |
| 395 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 396 | \begin{datadesc}{defaultTestLoader} |
| 397 | Instance of the \class{TestLoader} class which can be shared. If no |
| 398 | customization of the \class{TestLoader} is needed, this instance can |
| 399 | always be used instead of creating new instances. |
| 400 | \end{datadesc} |
| 401 | |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 402 | \begin{classdesc}{TextTestRunner}{\optional{stream\optional{, |
| 403 | descriptions\optional{, verbosity}}}} |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 404 | A basic test runner implementation which prints results on standard |
| 405 | output. It has a few configurable parameters, but is essentially |
| 406 | very simple. Graphical applications which run test suites should |
| 407 | provide alternate implementations. |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 408 | \end{classdesc} |
| 409 | |
| 410 | \begin{funcdesc}{main}{\optional{module\optional{, |
| 411 | defaultTest\optional{, argv\optional{, |
| 412 | testRunner\optional{, testRunner}}}}}} |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 413 | A command-line program that runs a set of tests; this is primarily |
| 414 | for making test modules conveniently executable. The simplest use |
| 415 | for this function is: |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 416 | |
| 417 | \begin{verbatim} |
| 418 | if __name__ == '__main__': |
| 419 | unittest.main() |
| 420 | \end{verbatim} |
| 421 | \end{funcdesc} |
| 422 | |
| 423 | |
| 424 | \subsection{TestCase Objects |
| 425 | \label{testcase-objects}} |
| 426 | |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 427 | Each \class{TestCase} instance represents a single test, but each |
| 428 | concrete subclass may be used to define multiple tests --- the |
| 429 | concrete class represents a single test fixture. The fixture is |
| 430 | created and cleaned up for each test case. |
| 431 | |
| 432 | \class{TestCase} instances provide three groups of methods: one group |
| 433 | used to run the test, another used by the test implementation to |
| 434 | check conditions and report failures, and some inquiry methods |
| 435 | allowing information about the test itself to be gathered. |
| 436 | |
| 437 | Methods in the first group are: |
| 438 | |
| 439 | \begin{methoddesc}[TestCase]{setUp}{} |
| 440 | Method called to prepare the test fixture. This is called |
| 441 | immediately before calling the test method; any exception raised by |
| 442 | this method will be considered an error rather than a test failure. |
| 443 | The default implementation does nothing. |
| 444 | \end{methoddesc} |
| 445 | |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 446 | \begin{methoddesc}[TestCase]{tearDown}{} |
| 447 | Method called immediately after the test method has been called and |
| 448 | the result recorded. This is called even if the test method raised |
| 449 | an exception, so the implementation in subclasses may need to be |
| 450 | particularly careful about checking internal state. Any exception |
| 451 | raised by this method will be considered an error rather than a test |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 452 | failure. This method will only be called if the \method{setUp()} |
| 453 | succeeds, regardless of the outcome of the test method. |
| 454 | The default implementation does nothing. |
| 455 | \end{methoddesc} |
| 456 | |
| 457 | \begin{methoddesc}[TestCase]{run}{\optional{result}} |
| 458 | Run the test, collecting the result into the test result object |
| 459 | passed as \var{result}. If \var{result} is omitted or \code{None}, |
| 460 | a temporary result object is created and used, but is not made |
| 461 | available to the caller. This is equivalent to simply calling the |
| 462 | \class{TestCase} instance. |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 463 | \end{methoddesc} |
| 464 | |
| 465 | \begin{methoddesc}[TestCase]{debug}{} |
| 466 | Run the test without collecting the result. This allows exceptions |
| 467 | raised by the test to be propogated to the caller, and can be used |
| 468 | to support running tests under a debugger. |
| 469 | \end{methoddesc} |
| 470 | |
| 471 | |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 472 | The test code can use any of the following methods to check for and |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 473 | report failures. |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 474 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 475 | \begin{methoddesc}[TestCase]{assert_}{expr\optional{, msg}} |
| 476 | \methodline{failUnless}{expr\optional{, msg}} |
| 477 | Signal a test failure if \var{expr} is false; the explanation for |
| 478 | the error will be \var{msg} if given, otherwise it will be |
| 479 | \code{None}. |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 480 | \end{methoddesc} |
| 481 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 482 | \begin{methoddesc}[TestCase]{assertEqual}{first, second\optional{, msg}} |
| 483 | \methodline{failUnlessEqual}{first, second\optional{, msg}} |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 484 | Test that \var{first} and \var{second} are equal. If the values do |
| 485 | not compare equal, the test will fail with the explanation given by |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 486 | \var{msg}, or \code{None}. Note that using \method{failUnlessEqual()} |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 487 | improves upon doing the comparison as the first parameter to |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 488 | \method{failUnless()}: the default value for \var{msg} can be |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 489 | computed to include representations of both \var{first} and |
| 490 | \var{second}. |
| 491 | \end{methoddesc} |
| 492 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 493 | \begin{methoddesc}[TestCase]{assertNotEqual}{first, second\optional{, msg}} |
| 494 | \methodline{failIfEqual}{first, second\optional{, msg}} |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 495 | Test that \var{first} and \var{second} are not equal. If the values |
| 496 | do compare equal, the test will fail with the explanation given by |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 497 | \var{msg}, or \code{None}. Note that using \method{failIfEqual()} |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 498 | improves upon doing the comparison as the first parameter to |
| 499 | \method{failUnless()} is that the default value for \var{msg} can be |
| 500 | computed to include representations of both \var{first} and |
| 501 | \var{second}. |
| 502 | \end{methoddesc} |
| 503 | |
Raymond Hettinger | c7b0769 | 2002-12-29 17:59:24 +0000 | [diff] [blame] | 504 | \begin{methoddesc}[TestCase]{assertAlmostEqual}{first, second\optional{, |
| 505 | places\optional{, msg}}} |
| 506 | \methodline{failUnlessAlmostEqual}{first, second\optional{, |
| 507 | places\optional{, msg}}} |
| 508 | Test that \var{first} and \var{second} are approximately equal |
| 509 | by computing the difference, rounding to the given number of \var{places}, |
| 510 | and comparing to zero. Note that comparing a given number of decimal places |
| 511 | is not the same as comparing a given number of significant digits. |
| 512 | If the values do not compare equal, the test will fail with the explanation |
| 513 | given by \var{msg}, or \code{None}. |
| 514 | \end{methoddesc} |
| 515 | |
| 516 | \begin{methoddesc}[TestCase]{assertNotAlmostEqual}{first, second\optional{, |
| 517 | places\optional{, msg}}} |
| 518 | \methodline{failIfAlmostEqual}{first, second\optional{, |
| 519 | places\optional{, msg}}} |
| 520 | Test that \var{first} and \var{second} are not approximately equal |
| 521 | by computing the difference, rounding to the given number of \var{places}, |
| 522 | and comparing to zero. Note that comparing a given number of decimal places |
| 523 | is not the same as comparing a given number of significant digits. |
| 524 | If the values do not compare equal, the test will fail with the explanation |
| 525 | given by \var{msg}, or \code{None}. |
| 526 | \end{methoddesc} |
| 527 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 528 | \begin{methoddesc}[TestCase]{assertRaises}{exception, callable, \moreargs} |
| 529 | \methodline{failUnlessRaises}{exception, callable, \moreargs} |
| 530 | Test that an exception is raised when \var{callable} is called with |
| 531 | any positional or keyword arguments that are also passed to |
| 532 | \method{assertRaises()}. The test passes if \var{exception} is |
| 533 | raised, is an error if another exception is raised, or fails if no |
| 534 | exception is raised. To catch any of a group of exceptions, a tuple |
| 535 | containing the exception classes may be passed as \var{exception}. |
| 536 | \end{methoddesc} |
| 537 | |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 538 | \begin{methoddesc}[TestCase]{failIf}{expr\optional{, msg}} |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 539 | The inverse of the \method{failUnless()} method is the |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 540 | \method{failIf()} method. This signals a test failure if \var{expr} |
| 541 | is true, with \var{msg} or \code{None} for the error message. |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 542 | \end{methoddesc} |
| 543 | |
| 544 | \begin{methoddesc}[TestCase]{fail}{\optional{msg}} |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 545 | Signals a test failure unconditionally, with \var{msg} or |
| 546 | \code{None} for the error message. |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 547 | \end{methoddesc} |
| 548 | |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 549 | \begin{memberdesc}[TestCase]{failureException} |
| 550 | This class attribute gives the exception raised by the |
| 551 | \method{test()} method. If a test framework needs to use a |
| 552 | specialized exception, possibly to carry additional information, it |
| 553 | must subclass this exception in order to ``play fair'' with the |
| 554 | framework. The initial value of this attribute is |
| 555 | \exception{AssertionError}. |
| 556 | \end{memberdesc} |
| 557 | |
Fred Drake | 29be701 | 2001-04-10 22:25:06 +0000 | [diff] [blame] | 558 | |
| 559 | Testing frameworks can use the following methods to collect |
| 560 | information on the test: |
| 561 | |
| 562 | \begin{methoddesc}[TestCase]{countTestCases}{} |
| 563 | Return the number of tests represented by the this test object. For |
| 564 | \class{TestCase} instances, this will always be \code{1}, but this |
| 565 | method is also implemented by the \class{TestSuite} class, which can |
| 566 | return larger values. |
| 567 | \end{methoddesc} |
| 568 | |
| 569 | \begin{methoddesc}[TestCase]{defaultTestResult}{} |
| 570 | Return the default type of test result object to be used to run this |
| 571 | test. |
| 572 | \end{methoddesc} |
| 573 | |
| 574 | \begin{methoddesc}[TestCase]{id}{} |
| 575 | Return a string identifying the specific test case. This is usually |
| 576 | the full name of the test method, including the module and class |
| 577 | names. |
| 578 | \end{methoddesc} |
| 579 | |
| 580 | \begin{methoddesc}[TestCase]{shortDescription}{} |
| 581 | Returns a one-line description of the test, or \code{None} if no |
| 582 | description has been provided. The default implementation of this |
| 583 | method returns the first line of the test method's docstring, if |
| 584 | available, or \code{None}. |
| 585 | \end{methoddesc} |
| 586 | |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 587 | |
| 588 | \subsection{TestSuite Objects |
| 589 | \label{testsuite-objects}} |
| 590 | |
| 591 | \class{TestSuite} objects behave much like \class{TestCase} objects, |
| 592 | except they do not actually implement a test. Instead, they are used |
| 593 | to aggregate tests into groups that should be run together. Some |
| 594 | additional methods are available to add tests to \class{TestSuite} |
| 595 | instances: |
| 596 | |
| 597 | \begin{methoddesc}[TestSuite]{addTest}{test} |
| 598 | Add a \class{TestCase} or \class{TestSuite} to the set of tests that |
| 599 | make up the suite. |
| 600 | \end{methoddesc} |
| 601 | |
| 602 | \begin{methoddesc}[TestSuite]{addTests}{tests} |
| 603 | Add all the tests from a sequence of \class{TestCase} and |
| 604 | \class{TestSuite} instances to this test suite. |
| 605 | \end{methoddesc} |
| 606 | |
Fred Drake | 4d17b30 | 2001-09-06 15:51:56 +0000 | [diff] [blame] | 607 | The \method{run()} method is also slightly different: |
| 608 | |
| 609 | \begin{methoddesc}[TestSuite]{run}{result} |
| 610 | Run the tests associated with this suite, collecting the result into |
| 611 | the test result object passed as \var{result}. Note that unlike |
| 612 | \method{TestCase.run()}, \method{TestSuite.run()} requires the |
| 613 | result object to be passed in. |
| 614 | \end{methoddesc} |
| 615 | |
| 616 | In the typical usage of a \class{TestSuite} object, the \method{run()} |
| 617 | method is invoked by a \class{TestRunner} rather than by the end-user |
| 618 | test harness. |
| 619 | |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 620 | |
| 621 | \subsection{TestResult Objects |
| 622 | \label{testresult-objects}} |
| 623 | |
| 624 | A \class{TestResult} object stores the results of a set of tests. The |
| 625 | \class{TestCase} and \class{TestSuite} classes ensure that results are |
| 626 | properly stored; test authors do not need to worry about recording the |
| 627 | outcome of tests. |
| 628 | |
| 629 | Testing frameworks built on top of \refmodule{unittest} may want |
| 630 | access to the \class{TestResult} object generated by running a set of |
| 631 | tests for reporting purposes; a \class{TestResult} instance is |
| 632 | returned by the \method{TestRunner.run()} method for this purpose. |
| 633 | |
| 634 | Each instance holds the total number of tests run, and collections of |
| 635 | failures and errors that occurred among those test runs. The |
| 636 | collections contain tuples of \code{(\var{testcase}, |
Fred Drake | 387c8b5 | 2002-07-02 22:34:44 +0000 | [diff] [blame] | 637 | \var{traceback})}, where \var{traceback} is a string containing a |
| 638 | formatted version of the traceback for the exception. |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 639 | |
| 640 | \class{TestResult} instances have the following attributes that will |
| 641 | be of interest when inspecting the results of running a set of tests: |
| 642 | |
| 643 | \begin{memberdesc}[TestResult]{errors} |
| 644 | A list containing pairs of \class{TestCase} instances and the |
Fred Drake | 387c8b5 | 2002-07-02 22:34:44 +0000 | [diff] [blame] | 645 | formatted tracebacks for tests which raised an exception but did not |
| 646 | signal a test failure. |
Fred Drake | c412617 | 2002-07-02 22:46:42 +0000 | [diff] [blame] | 647 | \versionchanged[Contains formatted tracebacks instead of |
| 648 | \function{sys.exc_info()} results]{2.2} |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 649 | \end{memberdesc} |
| 650 | |
| 651 | \begin{memberdesc}[TestResult]{failures} |
| 652 | A list containing pairs of \class{TestCase} instances and the |
Fred Drake | 387c8b5 | 2002-07-02 22:34:44 +0000 | [diff] [blame] | 653 | formatted tracebacks for tests which signalled a failure in the code |
| 654 | under test. |
Fred Drake | c412617 | 2002-07-02 22:46:42 +0000 | [diff] [blame] | 655 | \versionchanged[Contains formatted tracebacks instead of |
| 656 | \function{sys.exc_info()} results]{2.2} |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 657 | \end{memberdesc} |
| 658 | |
| 659 | \begin{memberdesc}[TestResult]{testsRun} |
| 660 | The number of tests which have been started. |
| 661 | \end{memberdesc} |
| 662 | |
| 663 | \begin{methoddesc}[TestResult]{wasSuccessful}{} |
| 664 | Returns true if all tests run so far have passed, otherwise returns |
| 665 | false. |
| 666 | \end{methoddesc} |
| 667 | |
| 668 | |
| 669 | The following methods of the \class{TestResult} class are used to |
| 670 | maintain the internal data structures, and mmay be extended in |
| 671 | subclasses to support additional reporting requirements. This is |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 672 | particularly useful in building tools which support interactive |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 673 | reporting while tests are being run. |
| 674 | |
| 675 | \begin{methoddesc}[TestResult]{startTest}{test} |
| 676 | Called when the test case \var{test} is about to be run. |
| 677 | \end{methoddesc} |
| 678 | |
| 679 | \begin{methoddesc}[TestResult]{stopTest}{test} |
| 680 | Called when the test case \var{test} has been executed, regardless |
| 681 | of the outcome. |
| 682 | \end{methoddesc} |
| 683 | |
| 684 | \begin{methoddesc}[TestResult]{addError}{test, err} |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 685 | Called when the test case \var{test} raises an exception without |
| 686 | signalling a test failure. \var{err} is a tuple of the form |
| 687 | returned by \function{sys.exc_info()}: \code{(\var{type}, |
| 688 | \var{value}, \var{traceback})}. |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 689 | \end{methoddesc} |
| 690 | |
| 691 | \begin{methoddesc}[TestResult]{addFailure}{test, err} |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 692 | Called when the test case \var{test} signals a failure. |
Fred Drake | 0056a42 | 2001-04-12 04:50:06 +0000 | [diff] [blame] | 693 | \var{err} is a tuple of the form returned by |
| 694 | \function{sys.exc_info()}: \code{(\var{type}, \var{value}, |
| 695 | \var{traceback})}. |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 696 | \end{methoddesc} |
| 697 | |
| 698 | \begin{methoddesc}[TestResult]{addSuccess}{test} |
| 699 | This method is called for a test that does not fail; \var{test} is |
| 700 | the test case object. |
| 701 | \end{methoddesc} |
| 702 | |
| 703 | |
| 704 | One additional method is available for \class{TestResult} objects: |
| 705 | |
| 706 | \begin{methoddesc}[TestResult]{stop}{} |
| 707 | This method can be called to signal that the set of tests being run |
| 708 | should be aborted. Once this has been called, the |
| 709 | \class{TestRunner} object return to its caller without running any |
| 710 | additional tests. This is used by the \class{TextTestRunner} class |
| 711 | to stop the test framework when the user signals an interrupt from |
Fred Drake | 8ee679f | 2001-07-14 02:50:55 +0000 | [diff] [blame] | 712 | the keyboard. Interactive tools which provide runners can use this |
| 713 | in a similar manner. |
Fred Drake | b9ad228 | 2001-04-07 05:41:39 +0000 | [diff] [blame] | 714 | \end{methoddesc} |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 715 | |
| 716 | |
| 717 | \subsection{TestLoader Objects |
| 718 | \label{testloader-objects}} |
| 719 | |
| 720 | The \class{TestLoader} class is used to create test suites from |
| 721 | classes and modules. Normally, there is no need to create an instance |
| 722 | of this class; the \refmodule{unittest} module provides an instance |
| 723 | that can be shared as the \code{defaultTestLoader} module attribute. |
| 724 | Using a subclass or instance would allow customization of some |
| 725 | configurable properties. |
| 726 | |
| 727 | \class{TestLoader} objects have the following methods: |
| 728 | |
| 729 | \begin{methoddesc}[TestLoader]{loadTestsFromTestCase}{testCaseClass} |
| 730 | Return a suite of all tests cases contained in the |
| 731 | \class{TestCase}-derived class \class{testCaseClass}. |
| 732 | \end{methoddesc} |
| 733 | |
| 734 | \begin{methoddesc}[TestLoader]{loadTestsFromModule}{module} |
| 735 | Return a suite of all tests cases contained in the given module. |
| 736 | This method searches \var{module} for classes derived from |
| 737 | \class{TestCase} and creates an instance of the class for each test |
| 738 | method defined for the class. |
| 739 | |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 740 | \warning{While using a hierarchy of |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 741 | \class{Testcase}-derived classes can be convenient in sharing |
| 742 | fixtures and helper functions, defining test methods on base classes |
| 743 | that are not intended to be instantiated directly does not play well |
| 744 | with this method. Doing so, however, can be useful when the |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 745 | fixtures are different and defined in subclasses.} |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 746 | \end{methoddesc} |
| 747 | |
| 748 | \begin{methoddesc}[TestLoader]{loadTestsFromName}{name\optional{, module}} |
| 749 | Return a suite of all tests cases given a string specifier. |
| 750 | |
Fred Drake | 4d17b30 | 2001-09-06 15:51:56 +0000 | [diff] [blame] | 751 | The specifier \var{name} is a ``dotted name'' that may resolve |
| 752 | either to a module, a test case class, a test method within a test |
| 753 | case class, or a callable object which returns a \class{TestCase} or |
| 754 | \class{TestSuite} instance. For example, if you have a module |
| 755 | \module{SampleTests} containing a \class{TestCase}-derived class |
| 756 | \class{SampleTestCase} with three test methods (\method{test_one()}, |
| 757 | \method{test_two()}, and \method{test_three()}), the specifier |
| 758 | \code{'SampleTests.SampleTestCase'} would cause this method to |
| 759 | return a suite which will run all three test methods. Using the |
| 760 | specifier \code{'SampleTests.SampleTestCase.test_two'} would cause |
| 761 | it to return a test suite which will run only the |
| 762 | \method{test_two()} test method. The specifier can refer to modules |
| 763 | and packages which have not been imported; they will be imported as |
| 764 | a side-effect. |
Fred Drake | 62a2669 | 2001-04-12 19:34:38 +0000 | [diff] [blame] | 765 | |
| 766 | The method optionally resolves \var{name} relative to a given module. |
| 767 | \end{methoddesc} |
| 768 | |
| 769 | \begin{methoddesc}[TestLoader]{loadTestsFromNames}{names\optional{, module}} |
| 770 | Similar to \method{loadTestsFromName()}, but takes a sequence of |
| 771 | names rather than a single name. The return value is a test suite |
| 772 | which supports all the tests defined for each name. |
| 773 | \end{methoddesc} |
| 774 | |
| 775 | \begin{methoddesc}[TestLoader]{getTestCaseNames}{testCaseClass} |
| 776 | Return a sorted sequence of method names found within |
| 777 | \var{testCaseClass}. |
| 778 | \end{methoddesc} |
| 779 | |
| 780 | |
| 781 | The following attributes of a \class{TestLoader} can be configured |
| 782 | either by subclassing or assignment on an instance: |
| 783 | |
| 784 | \begin{memberdesc}[TestLoader]{testMethodPrefix} |
| 785 | String giving the prefix of method names which will be interpreted |
| 786 | as test methods. The default value is \code{'test'}. |
| 787 | \end{memberdesc} |
| 788 | |
| 789 | \begin{memberdesc}[TestLoader]{sortTestMethodsUsing} |
| 790 | Function to be used to compare method names when sorting them in |
| 791 | \method{getTestCaseNames()}. The default value is the built-in |
| 792 | \function{cmp()} function; it can be set to \code{None} to disable |
| 793 | the sort. |
| 794 | \end{memberdesc} |
| 795 | |
| 796 | \begin{memberdesc}[TestLoader]{suiteClass} |
| 797 | Callable object that constructs a test suite from a list of tests. |
| 798 | No methods on the resulting object are needed. The default value is |
| 799 | the \class{TestSuite} class. |
| 800 | \end{memberdesc} |
Fred Drake | 387c8b5 | 2002-07-02 22:34:44 +0000 | [diff] [blame] | 801 | |
| 802 | |
| 803 | \subsection{Getting Extended Error Information |
| 804 | \label{unittest-error-info}} |
| 805 | |
| 806 | Some applications can make use of more error information (for example, |
| 807 | an integrated development environment, or IDE). Such an application |
| 808 | can retrieve supplemental information about errors and failures by |
| 809 | using an alternate \class{TestResult} implementation, and extending |
| 810 | the \method{defaultTestResult()} method of the \class{TestCase} class |
| 811 | to provide it. |
| 812 | |
| 813 | Here is a brief example of a \class{TestResult} subclass which stores |
| 814 | the actual exception and traceback objects. (Be aware that storing |
| 815 | traceback objects can cause a great deal of memory not to be reclaimed |
| 816 | when it otherwise would be, which can have effects that affect the |
| 817 | behavior of the tests.) |
| 818 | |
| 819 | \begin{verbatim} |
| 820 | import unittest |
| 821 | |
| 822 | class MyTestCase(unittest.TestCase): |
| 823 | def defaultTestResult(self): |
| 824 | return MyTestResult() |
| 825 | |
| 826 | class MyTestResult(unittest.TestResult): |
| 827 | def __init__(self): |
| 828 | self.errors_tb = [] |
| 829 | self.failures_tb = [] |
| 830 | |
| 831 | def addError(self, test, err): |
| 832 | self.errors_tb.append((test, err)) |
| 833 | unittest.TestResult.addError(self, test, err) |
| 834 | |
| 835 | def addFailure(self, test, err): |
| 836 | self.failures_tb.append((test, err)) |
| 837 | unittest.TestResult.addFailure(self, test, err) |
| 838 | \end{verbatim} |
| 839 | |
| 840 | Tests written using \class{MyTestCase} as the base class, instead of |
| 841 | \class{TestCase}, will allow tools to extract additional information |
| 842 | from the results object. |