| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="lib.html" title='Python Library Reference' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="testsuite-objects.html" /> |
| 13 | <link rel="prev" href="unittest-contents.html" /> |
| 14 | <link rel="parent" href="module-unittest.html" /> |
| 15 | <link rel="next" href="testsuite-objects.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>5.3.5 TestCase Objects </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="5.3.4 Classes and functions" |
| 25 | href="unittest-contents.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="5.3 unittest " |
| 28 | href="module-unittest.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="5.3.6 TestSuite Objects" |
| 31 | href="testsuite-objects.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Library Reference</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 38 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="unittest-contents.html">5.3.4 Classes and functions</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="module-unittest.html">5.3 unittest </A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="testsuite-objects.html">5.3.6 TestSuite Objects</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION007350000000000000000"></A><A NAME="testcase-objects"></A> |
| 56 | <BR> |
| 57 | 5.3.5 TestCase Objects |
| 58 | |
| 59 | </H2> |
| 60 | |
| 61 | <P> |
| 62 | Each <tt class="class">TestCase</tt> instance represents a single test, but each |
| 63 | concrete subclass may be used to define multiple tests -- the |
| 64 | concrete class represents a single test fixture. The fixture is |
| 65 | created and cleaned up for each test case. |
| 66 | |
| 67 | <P> |
| 68 | <tt class="class">TestCase</tt> instances provide three groups of methods: one group |
| 69 | used to run the test, another used by the test implementation to |
| 70 | check conditions and report failures, and some inquiry methods |
| 71 | allowing information about the test itself to be gathered. |
| 72 | |
| 73 | <P> |
| 74 | Methods in the first group are: |
| 75 | |
| 76 | <P> |
| 77 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 78 | <td><nobr><b><tt id='l2h-1135' xml:id='l2h-1135' class="method">setUp</tt></b>(</nobr></td> |
| 79 | <td><var></var>)</td></tr></table></dt> |
| 80 | <dd> |
| 81 | Method called to prepare the test fixture. This is called |
| 82 | immediately before calling the test method; any exception raised by |
| 83 | this method will be considered an error rather than a test failure. |
| 84 | The default implementation does nothing. |
| 85 | </dl> |
| 86 | |
| 87 | <P> |
| 88 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 89 | <td><nobr><b><tt id='l2h-1136' xml:id='l2h-1136' class="method">tearDown</tt></b>(</nobr></td> |
| 90 | <td><var></var>)</td></tr></table></dt> |
| 91 | <dd> |
| 92 | Method called immediately after the test method has been called and |
| 93 | the result recorded. This is called even if the test method raised |
| 94 | an exception, so the implementation in subclasses may need to be |
| 95 | particularly careful about checking internal state. Any exception |
| 96 | raised by this method will be considered an error rather than a test |
| 97 | failure. This method will only be called if the <tt class="method">setUp()</tt> |
| 98 | succeeds, regardless of the outcome of the test method. |
| 99 | The default implementation does nothing. |
| 100 | </dl> |
| 101 | |
| 102 | <P> |
| 103 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 104 | <td><nobr><b><tt id='l2h-1137' xml:id='l2h-1137' class="method">run</tt></b>(</nobr></td> |
| 105 | <td><var></var><big>[</big><var>result</var><big>]</big><var></var>)</td></tr></table></dt> |
| 106 | <dd> |
| 107 | Run the test, collecting the result into the test result object |
| 108 | passed as <var>result</var>. If <var>result</var> is omitted or <tt class="constant">None</tt>, |
| 109 | a temporary result object is created and used, but is not made |
| 110 | available to the caller. This is equivalent to simply calling the |
| 111 | <tt class="class">TestCase</tt> instance. |
| 112 | </dl> |
| 113 | |
| 114 | <P> |
| 115 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 116 | <td><nobr><b><tt id='l2h-1138' xml:id='l2h-1138' class="method">debug</tt></b>(</nobr></td> |
| 117 | <td><var></var>)</td></tr></table></dt> |
| 118 | <dd> |
| 119 | Run the test without collecting the result. This allows exceptions |
| 120 | raised by the test to be propagated to the caller, and can be used |
| 121 | to support running tests under a debugger. |
| 122 | </dl> |
| 123 | |
| 124 | <P> |
| 125 | The test code can use any of the following methods to check for and |
| 126 | report failures. |
| 127 | |
| 128 | <P> |
| 129 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 130 | <td><nobr><b><tt id='l2h-1139' xml:id='l2h-1139' class="method">assert_</tt></b>(</nobr></td> |
| 131 | <td><var>expr</var><big>[</big><var>, msg</var><big>]</big><var></var>)</td></tr></table></dt> |
| 132 | <dd> |
| 133 | <dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 134 | <td><nobr><b><tt id='l2h-1140' xml:id='l2h-1140' class="method">failUnless</tt></b>(</nobr></td> |
| 135 | <td><var>expr</var><big>[</big><var>, msg</var><big>]</big><var></var>)</td></tr></table></dt> |
| 136 | <dd> Signal a test failure if <var>expr</var> is false; the explanation for |
| 137 | the error will be <var>msg</var> if given, otherwise it will be |
| 138 | <tt class="constant">None</tt>. |
| 139 | </dl> |
| 140 | |
| 141 | <P> |
| 142 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 143 | <td><nobr><b><tt id='l2h-1141' xml:id='l2h-1141' class="method">assertEqual</tt></b>(</nobr></td> |
| 144 | <td><var>first, second</var><big>[</big><var>, msg</var><big>]</big><var></var>)</td></tr></table></dt> |
| 145 | <dd> |
| 146 | <dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 147 | <td><nobr><b><tt id='l2h-1142' xml:id='l2h-1142' class="method">failUnlessEqual</tt></b>(</nobr></td> |
| 148 | <td><var>first, second</var><big>[</big><var>, msg</var><big>]</big><var></var>)</td></tr></table></dt> |
| 149 | <dd> Test that <var>first</var> and <var>second</var> are equal. If the values do |
| 150 | not compare equal, the test will fail with the explanation given by |
| 151 | <var>msg</var>, or <tt class="constant">None</tt>. Note that using <tt class="method">failUnlessEqual()</tt> |
| 152 | improves upon doing the comparison as the first parameter to |
| 153 | <tt class="method">failUnless()</tt>: the default value for <var>msg</var> can be |
| 154 | computed to include representations of both <var>first</var> and |
| 155 | <var>second</var>. |
| 156 | </dl> |
| 157 | |
| 158 | <P> |
| 159 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 160 | <td><nobr><b><tt id='l2h-1143' xml:id='l2h-1143' class="method">assertNotEqual</tt></b>(</nobr></td> |
| 161 | <td><var>first, second</var><big>[</big><var>, msg</var><big>]</big><var></var>)</td></tr></table></dt> |
| 162 | <dd> |
| 163 | <dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 164 | <td><nobr><b><tt id='l2h-1144' xml:id='l2h-1144' class="method">failIfEqual</tt></b>(</nobr></td> |
| 165 | <td><var>first, second</var><big>[</big><var>, msg</var><big>]</big><var></var>)</td></tr></table></dt> |
| 166 | <dd> Test that <var>first</var> and <var>second</var> are not equal. If the values |
| 167 | do compare equal, the test will fail with the explanation given by |
| 168 | <var>msg</var>, or <tt class="constant">None</tt>. Note that using <tt class="method">failIfEqual()</tt> |
| 169 | improves upon doing the comparison as the first parameter to |
| 170 | <tt class="method">failUnless()</tt> is that the default value for <var>msg</var> can be |
| 171 | computed to include representations of both <var>first</var> and |
| 172 | <var>second</var>. |
| 173 | </dl> |
| 174 | |
| 175 | <P> |
| 176 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 177 | <td><nobr><b><tt id='l2h-1145' xml:id='l2h-1145' class="method">assertAlmostEqual</tt></b>(</nobr></td> |
| 178 | <td><var>first, second</var><big>[</big><var>, |
| 179 | places</var><big>[</big><var>, msg</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 180 | <dd> |
| 181 | <dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 182 | <td><nobr><b><tt id='l2h-1146' xml:id='l2h-1146' class="method">failUnlessAlmostEqual</tt></b>(</nobr></td> |
| 183 | <td><var>first, second</var><big>[</big><var>, |
| 184 | places</var><big>[</big><var>, msg</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 185 | <dd> Test that <var>first</var> and <var>second</var> are approximately equal |
| 186 | by computing the difference, rounding to the given number of <var>places</var>, |
| 187 | and comparing to zero. Note that comparing a given number of decimal places |
| 188 | is not the same as comparing a given number of significant digits. |
| 189 | If the values do not compare equal, the test will fail with the explanation |
| 190 | given by <var>msg</var>, or <tt class="constant">None</tt>. |
| 191 | </dl> |
| 192 | |
| 193 | <P> |
| 194 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 195 | <td><nobr><b><tt id='l2h-1147' xml:id='l2h-1147' class="method">assertNotAlmostEqual</tt></b>(</nobr></td> |
| 196 | <td><var>first, second</var><big>[</big><var>, |
| 197 | places</var><big>[</big><var>, msg</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 198 | <dd> |
| 199 | <dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 200 | <td><nobr><b><tt id='l2h-1148' xml:id='l2h-1148' class="method">failIfAlmostEqual</tt></b>(</nobr></td> |
| 201 | <td><var>first, second</var><big>[</big><var>, |
| 202 | places</var><big>[</big><var>, msg</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 203 | <dd> Test that <var>first</var> and <var>second</var> are not approximately equal |
| 204 | by computing the difference, rounding to the given number of <var>places</var>, |
| 205 | and comparing to zero. Note that comparing a given number of decimal places |
| 206 | is not the same as comparing a given number of significant digits. |
| 207 | If the values do not compare equal, the test will fail with the explanation |
| 208 | given by <var>msg</var>, or <tt class="constant">None</tt>. |
| 209 | </dl> |
| 210 | |
| 211 | <P> |
| 212 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 213 | <td><nobr><b><tt id='l2h-1149' xml:id='l2h-1149' class="method">assertRaises</tt></b>(</nobr></td> |
| 214 | <td><var>exception, callable, ...</var>)</td></tr></table></dt> |
| 215 | <dd> |
| 216 | <dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 217 | <td><nobr><b><tt id='l2h-1150' xml:id='l2h-1150' class="method">failUnlessRaises</tt></b>(</nobr></td> |
| 218 | <td><var>exception, callable, ...</var>)</td></tr></table></dt> |
| 219 | <dd> Test that an exception is raised when <var>callable</var> is called with |
| 220 | any positional or keyword arguments that are also passed to |
| 221 | <tt class="method">assertRaises()</tt>. The test passes if <var>exception</var> is |
| 222 | raised, is an error if another exception is raised, or fails if no |
| 223 | exception is raised. To catch any of a group of exceptions, a tuple |
| 224 | containing the exception classes may be passed as <var>exception</var>. |
| 225 | </dl> |
| 226 | |
| 227 | <P> |
| 228 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 229 | <td><nobr><b><tt id='l2h-1151' xml:id='l2h-1151' class="method">failIf</tt></b>(</nobr></td> |
| 230 | <td><var>expr</var><big>[</big><var>, msg</var><big>]</big><var></var>)</td></tr></table></dt> |
| 231 | <dd> |
| 232 | The inverse of the <tt class="method">failUnless()</tt> method is the |
| 233 | <tt class="method">failIf()</tt> method. This signals a test failure if <var>expr</var> |
| 234 | is true, with <var>msg</var> or <tt class="constant">None</tt> for the error message. |
| 235 | </dl> |
| 236 | |
| 237 | <P> |
| 238 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 239 | <td><nobr><b><tt id='l2h-1152' xml:id='l2h-1152' class="method">fail</tt></b>(</nobr></td> |
| 240 | <td><var></var><big>[</big><var>msg</var><big>]</big><var></var>)</td></tr></table></dt> |
| 241 | <dd> |
| 242 | Signals a test failure unconditionally, with <var>msg</var> or |
| 243 | <tt class="constant">None</tt> for the error message. |
| 244 | </dl> |
| 245 | |
| 246 | <P> |
| 247 | <dl><dt><b><tt id='l2h-1153' xml:id='l2h-1153' class="member">failureException</tt></b></dt> |
| 248 | <dd> |
| 249 | This class attribute gives the exception raised by the |
| 250 | <tt class="method">test()</tt> method. If a test framework needs to use a |
| 251 | specialized exception, possibly to carry additional information, it |
| 252 | must subclass this exception in order to ``play fair'' with the |
| 253 | framework. The initial value of this attribute is |
| 254 | <tt class="exception">AssertionError</tt>. |
| 255 | </dl> |
| 256 | |
| 257 | <P> |
| 258 | Testing frameworks can use the following methods to collect |
| 259 | information on the test: |
| 260 | |
| 261 | <P> |
| 262 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 263 | <td><nobr><b><tt id='l2h-1154' xml:id='l2h-1154' class="method">countTestCases</tt></b>(</nobr></td> |
| 264 | <td><var></var>)</td></tr></table></dt> |
| 265 | <dd> |
| 266 | Return the number of tests represented by the this test object. For |
| 267 | <tt class="class">TestCase</tt> instances, this will always be <code>1</code>, but this |
| 268 | method is also implemented by the <tt class="class">TestSuite</tt> class, which can |
| 269 | return larger values. |
| 270 | </dl> |
| 271 | |
| 272 | <P> |
| 273 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 274 | <td><nobr><b><tt id='l2h-1155' xml:id='l2h-1155' class="method">defaultTestResult</tt></b>(</nobr></td> |
| 275 | <td><var></var>)</td></tr></table></dt> |
| 276 | <dd> |
| 277 | Return the default type of test result object to be used to run this |
| 278 | test. |
| 279 | </dl> |
| 280 | |
| 281 | <P> |
| 282 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 283 | <td><nobr><b><tt id='l2h-1156' xml:id='l2h-1156' class="method">id</tt></b>(</nobr></td> |
| 284 | <td><var></var>)</td></tr></table></dt> |
| 285 | <dd> |
| 286 | Return a string identifying the specific test case. This is usually |
| 287 | the full name of the test method, including the module and class |
| 288 | names. |
| 289 | </dl> |
| 290 | |
| 291 | <P> |
| 292 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 293 | <td><nobr><b><tt id='l2h-1157' xml:id='l2h-1157' class="method">shortDescription</tt></b>(</nobr></td> |
| 294 | <td><var></var>)</td></tr></table></dt> |
| 295 | <dd> |
| 296 | Returns a one-line description of the test, or <tt class="constant">None</tt> if no |
| 297 | description has been provided. The default implementation of this |
| 298 | method returns the first line of the test method's docstring, if |
| 299 | available, or <tt class="constant">None</tt>. |
| 300 | </dl> |
| 301 | |
| 302 | <P> |
| 303 | |
| 304 | <DIV CLASS="navigation"> |
| 305 | <div class='online-navigation'> |
| 306 | <p></p><hr /> |
| 307 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 308 | <tr> |
| 309 | <td class='online-navigation'><a rel="prev" title="5.3.4 Classes and functions" |
| 310 | href="unittest-contents.html"><img src='../icons/previous.png' |
| 311 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 312 | <td class='online-navigation'><a rel="parent" title="5.3 unittest " |
| 313 | href="module-unittest.html"><img src='../icons/up.png' |
| 314 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 315 | <td class='online-navigation'><a rel="next" title="5.3.6 TestSuite Objects" |
| 316 | href="testsuite-objects.html"><img src='../icons/next.png' |
| 317 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 318 | <td align="center" width="100%">Python Library Reference</td> |
| 319 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 320 | href="contents.html"><img src='../icons/contents.png' |
| 321 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 322 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 323 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 324 | <td class='online-navigation'><a rel="index" title="Index" |
| 325 | href="genindex.html"><img src='../icons/index.png' |
| 326 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 327 | </tr></table> |
| 328 | <div class='online-navigation'> |
| 329 | <b class="navlabel">Previous:</b> |
| 330 | <a class="sectref" rel="prev" href="unittest-contents.html">5.3.4 Classes and functions</A> |
| 331 | <b class="navlabel">Up:</b> |
| 332 | <a class="sectref" rel="parent" href="module-unittest.html">5.3 unittest </A> |
| 333 | <b class="navlabel">Next:</b> |
| 334 | <a class="sectref" rel="next" href="testsuite-objects.html">5.3.6 TestSuite Objects</A> |
| 335 | </div> |
| 336 | </div> |
| 337 | <hr /> |
| 338 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 339 | </DIV> |
| 340 | <!--End of Navigation Panel--> |
| 341 | <ADDRESS> |
| 342 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 343 | </ADDRESS> |
| 344 | </BODY> |
| 345 | </HTML> |