Commit | Line | Data |
---|---|---|
920dae64 AT |
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> |