File: //usr/share/doc/python-docs-2.4.3/html/lib/doctest-DocTestRunner.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="doctest-OutputChecker.html" />
<link rel="prev" href="doctest-DocTestParser.html" />
<link rel="parent" href="doctest-advanced-api.html" />
<link rel="next" href="doctest-OutputChecker.html" />
<meta name='aesop' content='information' />
<title>5.2.6.5 DocTestRunner objects</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.2.6.4 DocTestParser objects"
href="doctest-DocTestParser.html"><img src='../icons/previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5.2.6 Advanced API"
href="doctest-advanced-api.html"><img src='../icons/up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="5.2.6.6 OutputChecker objects"
href="doctest-OutputChecker.html"><img src='../icons/next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='../icons/contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
border='0' height='32' alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
href="genindex.html"><img src='../icons/index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="doctest-DocTestParser.html">5.2.6.4 DocTestParser objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="doctest-advanced-api.html">5.2.6 Advanced API</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="doctest-OutputChecker.html">5.2.6.6 OutputChecker objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<H3><A NAME="SECTION007265000000000000000"></A><A NAME="doctest-DocTestRunner"></A>
<BR>
5.2.6.5 DocTestRunner objects
</H3>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-1100' xml:id='l2h-1100' class="class">DocTestRunner</tt></b>(</nobr></td>
<td><var></var><big>[</big><var>checker</var><big>]</big><var></var><big>[</big><var>,
verbose</var><big>]</big><var></var><big>[</big><var>, optionflags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
A processing class used to execute and verify the interactive
examples in a <tt class="class">DocTest</tt>.
<P>
The comparison between expected outputs and actual outputs is done
by an <tt class="class">OutputChecker</tt>. This comparison may be customized
with a number of option flags; see section <A href="doctest-options.html#doctest-options">5.2.3</A>
for more information. If the option flags are insufficient, then
the comparison may also be customized by passing a subclass of
<tt class="class">OutputChecker</tt> to the constructor.
<P>
The test runner's display output can be controlled in two ways.
First, an output function can be passed to
<tt class="method">TestRunner.run()</tt>; this function will be called with
strings that should be displayed. It defaults to
<code>sys.stdout.write</code>. If capturing the output is not
sufficient, then the display output can be also customized by
subclassing DocTestRunner, and overriding the methods
<tt class="method">report_start</tt>, <tt class="method">report_success</tt>,
<tt class="method">report_unexpected_exception</tt>, and <tt class="method">report_failure</tt>.
<P>
The optional keyword argument <var>checker</var> specifies the
<tt class="class">OutputChecker</tt> object (or drop-in replacement) that should
be used to compare the expected outputs to the actual outputs of
doctest examples.
<P>
The optional keyword argument <var>verbose</var> controls the
<tt class="class">DocTestRunner</tt>'s verbosity. If <var>verbose</var> is
<code>True</code>, then information is printed about each example, as it
is run. If <var>verbose</var> is <code>False</code>, then only failures are
printed. If <var>verbose</var> is unspecified, or <code>None</code>, then
verbose output is used iff the command-line switch <b class="programopt">-v</b>
is used.
<P>
The optional keyword argument <var>optionflags</var> can be used to
control how the test runner compares expected output to actual
output, and how it displays failures. For more information, see
section <A href="doctest-options.html#doctest-options">5.2.3</A>.
<P>
<span class="versionnote">New in version 2.4.</span>
</dl>
<P>
<tt class="class">DocTestParser</tt> defines the following methods:
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-1101' xml:id='l2h-1101' class="method">report_start</tt></b>(</nobr></td>
<td><var>out, test, example</var>)</td></tr></table></dt>
<dd>
Report that the test runner is about to process the given example.
This method is provided to allow subclasses of
<tt class="class">DocTestRunner</tt> to customize their output; it should not be
called directly.
<P>
<var>example</var> is the example about to be processed. <var>test</var> is
the test containing <var>example</var>. <var>out</var> is the output
function that was passed to <tt class="method">DocTestRunner.run()</tt>.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-1102' xml:id='l2h-1102' class="method">report_success</tt></b>(</nobr></td>
<td><var>out, test, example, got</var>)</td></tr></table></dt>
<dd>
Report that the given example ran successfully. This method is
provided to allow subclasses of <tt class="class">DocTestRunner</tt> to customize
their output; it should not be called directly.
<P>
<var>example</var> is the example about to be processed. <var>got</var> is
the actual output from the example. <var>test</var> is the test
containing <var>example</var>. <var>out</var> is the output function that
was passed to <tt class="method">DocTestRunner.run()</tt>.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-1103' xml:id='l2h-1103' class="method">report_failure</tt></b>(</nobr></td>
<td><var>out, test, example, got</var>)</td></tr></table></dt>
<dd>
Report that the given example failed. This method is provided to
allow subclasses of <tt class="class">DocTestRunner</tt> to customize their
output; it should not be called directly.
<P>
<var>example</var> is the example about to be processed. <var>got</var> is
the actual output from the example. <var>test</var> is the test
containing <var>example</var>. <var>out</var> is the output function that
was passed to <tt class="method">DocTestRunner.run()</tt>.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-1104' xml:id='l2h-1104' class="method">report_unexpected_exception</tt></b>(</nobr></td>
<td><var>out, test, example, exc_info</var>)</td></tr></table></dt>
<dd>
Report that the given example raised an unexpected exception.
This method is provided to allow subclasses of
<tt class="class">DocTestRunner</tt> to customize their output; it should not be
called directly.
<P>
<var>example</var> is the example about to be processed.
<var>exc_info</var> is a tuple containing information about the
unexpected exception (as returned by <tt class="function">sys.exc_info()</tt>).
<var>test</var> is the test containing <var>example</var>. <var>out</var> is the
output function that was passed to <tt class="method">DocTestRunner.run()</tt>.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-1105' xml:id='l2h-1105' class="method">run</tt></b>(</nobr></td>
<td><var>test</var><big>[</big><var>, compileflags</var><big>]</big><var></var><big>[</big><var>,
out</var><big>]</big><var></var><big>[</big><var>, clear_globs</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Run the examples in <var>test</var> (a <tt class="class">DocTest</tt> object), and
display the results using the writer function <var>out</var>.
<P>
The examples are run in the namespace <code>test.globs</code>. If
<var>clear_globs</var> is true (the default), then this namespace will
be cleared after the test runs, to help with garbage collection.
If you would like to examine the namespace after the test
completes, then use <var>clear_globs=False</var>.
<P>
<var>compileflags</var> gives the set of flags that should be used by
the Python compiler when running the examples. If not specified,
then it will default to the set of future-import flags that apply
to <var>globs</var>.
<P>
The output of each example is checked using the
<tt class="class">DocTestRunner</tt>'s output checker, and the results are
formatted by the <tt class="method">DocTestRunner.report_*</tt> methods.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><tt id='l2h-1106' xml:id='l2h-1106' class="method">summarize</tt></b>(</nobr></td>
<td><var></var><big>[</big><var>verbose</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Print a summary of all the test cases that have been run by this
DocTestRunner, and return a tuple "<tt class="samp">(<var>failure_count</var>,
<var>test_count</var>)</tt>".
<P>
The optional <var>verbose</var> argument controls how detailed the
summary is. If the verbosity is not specified, then the
<tt class="class">DocTestRunner</tt>'s verbosity is used.
</dl>
<P>
<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.2.6.4 DocTestParser objects"
href="doctest-DocTestParser.html"><img src='../icons/previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5.2.6 Advanced API"
href="doctest-advanced-api.html"><img src='../icons/up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="5.2.6.6 OutputChecker objects"
href="doctest-OutputChecker.html"><img src='../icons/next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='../icons/contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
border='0' height='32' alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
href="genindex.html"><img src='../icons/index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="doctest-DocTestParser.html">5.2.6.4 DocTestParser objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="doctest-advanced-api.html">5.2.6 Advanced API</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="doctest-OutputChecker.html">5.2.6.6 OutputChecker objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.3, documentation updated on 29 March 2006.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>