sam-t2/devtools/v9/html/python/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>&nbsp;<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&nbsp;<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&nbsp;<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.2, documentation updated on 28 September 2005.</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>