Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / doctest-DocTestRunner.html
CommitLineData
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="doctest-OutputChecker.html" />
13<link rel="prev" href="doctest-DocTestParser.html" />
14<link rel="parent" href="doctest-advanced-api.html" />
15<link rel="next" href="doctest-OutputChecker.html" />
16<meta name='aesop' content='information' />
17<title>5.2.6.5 DocTestRunner 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.2.6.4 DocTestParser objects"
25 href="doctest-DocTestParser.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.2.6 Advanced API"
28 href="doctest-advanced-api.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.2.6.6 OutputChecker objects"
31 href="doctest-OutputChecker.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="doctest-DocTestParser.html">5.2.6.4 DocTestParser objects</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="doctest-advanced-api.html">5.2.6 Advanced API</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="doctest-OutputChecker.html">5.2.6.6 OutputChecker objects</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H3><A NAME="SECTION007265000000000000000"></A><A NAME="doctest-DocTestRunner"></A>
56<BR>
575.2.6.5 DocTestRunner objects
58</H3>
59<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
60 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1100' xml:id='l2h-1100' class="class">DocTestRunner</tt></b>(</nobr></td>
61 <td><var></var><big>[</big><var>checker</var><big>]</big><var></var><big>[</big><var>,
62 verbose</var><big>]</big><var></var><big>[</big><var>, optionflags</var><big>]</big><var></var>)</td></tr></table></dt>
63<dd>
64 A processing class used to execute and verify the interactive
65 examples in a <tt class="class">DocTest</tt>.
66
67<P>
68The comparison between expected outputs and actual outputs is done
69 by an <tt class="class">OutputChecker</tt>. This comparison may be customized
70 with a number of option flags; see section&nbsp;<A href="doctest-options.html#doctest-options">5.2.3</A>
71 for more information. If the option flags are insufficient, then
72 the comparison may also be customized by passing a subclass of
73 <tt class="class">OutputChecker</tt> to the constructor.
74
75<P>
76The test runner's display output can be controlled in two ways.
77 First, an output function can be passed to
78 <tt class="method">TestRunner.run()</tt>; this function will be called with
79 strings that should be displayed. It defaults to
80 <code>sys.stdout.write</code>. If capturing the output is not
81 sufficient, then the display output can be also customized by
82 subclassing DocTestRunner, and overriding the methods
83 <tt class="method">report_start</tt>, <tt class="method">report_success</tt>,
84 <tt class="method">report_unexpected_exception</tt>, and <tt class="method">report_failure</tt>.
85
86<P>
87The optional keyword argument <var>checker</var> specifies the
88 <tt class="class">OutputChecker</tt> object (or drop-in replacement) that should
89 be used to compare the expected outputs to the actual outputs of
90 doctest examples.
91
92<P>
93The optional keyword argument <var>verbose</var> controls the
94 <tt class="class">DocTestRunner</tt>'s verbosity. If <var>verbose</var> is
95 <code>True</code>, then information is printed about each example, as it
96 is run. If <var>verbose</var> is <code>False</code>, then only failures are
97 printed. If <var>verbose</var> is unspecified, or <code>None</code>, then
98 verbose output is used iff the command-line switch <b class="programopt">-v</b>
99 is used.
100
101<P>
102The optional keyword argument <var>optionflags</var> can be used to
103 control how the test runner compares expected output to actual
104 output, and how it displays failures. For more information, see
105 section&nbsp;<A href="doctest-options.html#doctest-options">5.2.3</A>.
106
107<P>
108
109<span class="versionnote">New in version 2.4.</span>
110
111</dl>
112
113<P>
114<tt class="class">DocTestParser</tt> defines the following methods:
115
116<P>
117<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
118 <td><nobr><b><tt id='l2h-1101' xml:id='l2h-1101' class="method">report_start</tt></b>(</nobr></td>
119 <td><var>out, test, example</var>)</td></tr></table></dt>
120<dd>
121 Report that the test runner is about to process the given example.
122 This method is provided to allow subclasses of
123 <tt class="class">DocTestRunner</tt> to customize their output; it should not be
124 called directly.
125
126<P>
127<var>example</var> is the example about to be processed. <var>test</var> is
128 the test containing <var>example</var>. <var>out</var> is the output
129 function that was passed to <tt class="method">DocTestRunner.run()</tt>.
130</dl>
131
132<P>
133<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
134 <td><nobr><b><tt id='l2h-1102' xml:id='l2h-1102' class="method">report_success</tt></b>(</nobr></td>
135 <td><var>out, test, example, got</var>)</td></tr></table></dt>
136<dd>
137 Report that the given example ran successfully. This method is
138 provided to allow subclasses of <tt class="class">DocTestRunner</tt> to customize
139 their output; it should not be called directly.
140
141<P>
142<var>example</var> is the example about to be processed. <var>got</var> is
143 the actual output from the example. <var>test</var> is the test
144 containing <var>example</var>. <var>out</var> is the output function that
145 was passed to <tt class="method">DocTestRunner.run()</tt>.
146</dl>
147
148<P>
149<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
150 <td><nobr><b><tt id='l2h-1103' xml:id='l2h-1103' class="method">report_failure</tt></b>(</nobr></td>
151 <td><var>out, test, example, got</var>)</td></tr></table></dt>
152<dd>
153 Report that the given example failed. This method is provided to
154 allow subclasses of <tt class="class">DocTestRunner</tt> to customize their
155 output; it should not be called directly.
156
157<P>
158<var>example</var> is the example about to be processed. <var>got</var> is
159 the actual output from the example. <var>test</var> is the test
160 containing <var>example</var>. <var>out</var> is the output function that
161 was passed to <tt class="method">DocTestRunner.run()</tt>.
162</dl>
163
164<P>
165<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
166 <td><nobr><b><tt id='l2h-1104' xml:id='l2h-1104' class="method">report_unexpected_exception</tt></b>(</nobr></td>
167 <td><var>out, test, example, exc_info</var>)</td></tr></table></dt>
168<dd>
169 Report that the given example raised an unexpected exception.
170 This method is provided to allow subclasses of
171 <tt class="class">DocTestRunner</tt> to customize their output; it should not be
172 called directly.
173
174<P>
175<var>example</var> is the example about to be processed.
176 <var>exc_info</var> is a tuple containing information about the
177 unexpected exception (as returned by <tt class="function">sys.exc_info()</tt>).
178 <var>test</var> is the test containing <var>example</var>. <var>out</var> is the
179 output function that was passed to <tt class="method">DocTestRunner.run()</tt>.
180</dl>
181
182<P>
183<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
184 <td><nobr><b><tt id='l2h-1105' xml:id='l2h-1105' class="method">run</tt></b>(</nobr></td>
185 <td><var>test</var><big>[</big><var>, compileflags</var><big>]</big><var></var><big>[</big><var>,
186 out</var><big>]</big><var></var><big>[</big><var>, clear_globs</var><big>]</big><var></var>)</td></tr></table></dt>
187<dd>
188 Run the examples in <var>test</var> (a <tt class="class">DocTest</tt> object), and
189 display the results using the writer function <var>out</var>.
190
191<P>
192The examples are run in the namespace <code>test.globs</code>. If
193 <var>clear_globs</var> is true (the default), then this namespace will
194 be cleared after the test runs, to help with garbage collection.
195 If you would like to examine the namespace after the test
196 completes, then use <var>clear_globs=False</var>.
197
198<P>
199<var>compileflags</var> gives the set of flags that should be used by
200 the Python compiler when running the examples. If not specified,
201 then it will default to the set of future-import flags that apply
202 to <var>globs</var>.
203
204<P>
205The output of each example is checked using the
206 <tt class="class">DocTestRunner</tt>'s output checker, and the results are
207 formatted by the <tt class="method">DocTestRunner.report_*</tt> methods.
208</dl>
209
210<P>
211<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
212 <td><nobr><b><tt id='l2h-1106' xml:id='l2h-1106' class="method">summarize</tt></b>(</nobr></td>
213 <td><var></var><big>[</big><var>verbose</var><big>]</big><var></var>)</td></tr></table></dt>
214<dd>
215 Print a summary of all the test cases that have been run by this
216 DocTestRunner, and return a tuple "<tt class="samp">(<var>failure_count</var>,
217 <var>test_count</var>)</tt>".
218
219<P>
220The optional <var>verbose</var> argument controls how detailed the
221 summary is. If the verbosity is not specified, then the
222 <tt class="class">DocTestRunner</tt>'s verbosity is used.
223</dl>
224
225<P>
226
227<DIV CLASS="navigation">
228<div class='online-navigation'>
229<p></p><hr />
230<table align="center" width="100%" cellpadding="0" cellspacing="2">
231<tr>
232<td class='online-navigation'><a rel="prev" title="5.2.6.4 DocTestParser objects"
233 href="doctest-DocTestParser.html"><img src='../icons/previous.png'
234 border='0' height='32' alt='Previous Page' width='32' /></A></td>
235<td class='online-navigation'><a rel="parent" title="5.2.6 Advanced API"
236 href="doctest-advanced-api.html"><img src='../icons/up.png'
237 border='0' height='32' alt='Up One Level' width='32' /></A></td>
238<td class='online-navigation'><a rel="next" title="5.2.6.6 OutputChecker objects"
239 href="doctest-OutputChecker.html"><img src='../icons/next.png'
240 border='0' height='32' alt='Next Page' width='32' /></A></td>
241<td align="center" width="100%">Python Library Reference</td>
242<td class='online-navigation'><a rel="contents" title="Table of Contents"
243 href="contents.html"><img src='../icons/contents.png'
244 border='0' height='32' alt='Contents' width='32' /></A></td>
245<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
246 border='0' height='32' alt='Module Index' width='32' /></a></td>
247<td class='online-navigation'><a rel="index" title="Index"
248 href="genindex.html"><img src='../icons/index.png'
249 border='0' height='32' alt='Index' width='32' /></A></td>
250</tr></table>
251<div class='online-navigation'>
252<b class="navlabel">Previous:</b>
253<a class="sectref" rel="prev" href="doctest-DocTestParser.html">5.2.6.4 DocTestParser objects</A>
254<b class="navlabel">Up:</b>
255<a class="sectref" rel="parent" href="doctest-advanced-api.html">5.2.6 Advanced API</A>
256<b class="navlabel">Next:</b>
257<a class="sectref" rel="next" href="doctest-OutputChecker.html">5.2.6.6 OutputChecker objects</A>
258</div>
259</div>
260<hr />
261<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
262</DIV>
263<!--End of Navigation Panel-->
264<ADDRESS>
265See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
266</ADDRESS>
267</BODY>
268</HTML>