sam-t2/devtools/v8plus/html/python/lib/doctest-unittest-api.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-advanced-api.html" />
<link rel="prev" href="doctest-basic-api.html" />
<link rel="parent" href="module-doctest.html" />
<link rel="next" href="doctest-advanced-api.html" />
<meta name='aesop' content='information' />
<title>5.2.5 Unittest API</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.4 Basic API"
  href="doctest-basic-api.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 doctest  "
  href="module-doctest.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 Advanced API"
  href="doctest-advanced-api.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-basic-api.html">5.2.4 Basic API</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="doctest-advanced-api.html">5.2.6 Advanced API</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION007250000000000000000"></A><A NAME="doctest-unittest-api"></A>
<BR>
5.2.5 Unittest API
</H2>

<P>
As your collection of doctest'ed modules grows, you'll want a way to run
all their doctests systematically.  Prior to Python 2.4, <tt class="module"><a href="module-doctest.html">doctest</a></tt>
had a barely documented <tt class="class">Tester</tt> class that supplied a rudimentary
way to combine doctests from multiple modules. <tt class="class">Tester</tt> was feeble,
and in practice most serious Python testing frameworks build on the
<tt class="module"><a href="module-unittest.html">unittest</a></tt> module, which supplies many flexible ways to combine
tests from multiple sources.  So, in Python 2.4, <tt class="module"><a href="module-doctest.html">doctest</a></tt>'s
<tt class="class">Tester</tt> class is deprecated, and <tt class="module"><a href="module-doctest.html">doctest</a></tt> provides two
functions that can be used to create <tt class="module"><a href="module-unittest.html">unittest</a></tt> test suites from
modules and text files containing doctests.  These test suites can then be
run using <tt class="module"><a href="module-unittest.html">unittest</a></tt> test runners:

<P>
<div class="verbatim"><pre>
import unittest
import doctest
import my_module_with_doctests, and_another

suite = unittest.TestSuite()
for mod in my_module_with_doctests, and_another:
    suite.addTest(doctest.DocTestSuite(mod))
runner = unittest.TextTestRunner()
runner.run(suite)
</pre></div>

<P>
There are two main functions for creating <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt>
instances from text files and modules with doctests:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1077' xml:id='l2h-1077' class="function">DocFileSuite</tt></b>(</nobr></td>
  <td><var>*paths, **kw</var>)</td></tr></table></dt>
<dd>
  Convert doctest tests from one or more text files to a
  <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt>.

<P>
The returned <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> is to be run by the
  unittest framework and runs the interactive examples in each file.  If an
  example in any file fails, then the synthesized unit test fails, and a
  <tt class="exception">failureException</tt> exception is raised showing the name of the
  file containing the test and a (sometimes approximate) line number.

<P>
Pass one or more paths (as strings) to text files to be examined.

<P>
Options may be provided as keyword arguments:

<P>
Optional argument <var>module_relative</var> specifies how
  the filenames in <var>paths</var> should be interpreted:

<P>

<UL>
<LI>If <var>module_relative</var> is <code>True</code> (the default), then
        each filename specifies an OS-independent module-relative
        path.  By default, this path is relative to the calling
        module's directory; but if the <var>package</var> argument is
        specified, then it is relative to that package.  To ensure
        OS-independence, each filename should use <code>/</code> characters
        to separate path segments, and may not be an absolute path
        (i.e., it may not begin with <code>/</code>).
</LI>
<LI>If <var>module_relative</var> is <code>False</code>, then each filename
        specifies an OS-specific path.  The path may be absolute or
        relative; relative paths are resolved with respect to the
        current working directory.

</LI>
</UL>

<P>
Optional argument <var>package</var> is a Python package or the name
  of a Python package whose directory should be used as the base
  directory for module-relative filenames.  If no package is
  specified, then the calling module's directory is used as the base
  directory for module-relative filenames.  It is an error to specify
  <var>package</var> if <var>module_relative</var> is <code>False</code>.

<P>
Optional argument <var>setUp</var> specifies a set-up function for
  the test suite.  This is called before running the tests in each
  file.  The <var>setUp</var> function will be passed a <tt class="class">DocTest</tt>
  object.  The setUp function can access the test globals as the
  <var>globs</var> attribute of the test passed.

<P>
Optional argument <var>tearDown</var> specifies a tear-down function
  for the test suite.  This is called after running the tests in each
  file.  The <var>tearDown</var> function will be passed a <tt class="class">DocTest</tt>
  object.  The setUp function can access the test globals as the
  <var>globs</var> attribute of the test passed.

<P>
Optional argument <var>globs</var> is a dictionary containing the
  initial global variables for the tests.  A new copy of this
  dictionary is created for each test.  By default, <var>globs</var> is
  a new empty dictionary.

<P>
Optional argument <var>optionflags</var> specifies the default
  doctest options for the tests, created by or-ing together
  individual option flags.  See section&nbsp;<A href="doctest-options.html#doctest-options">5.2.3</A>.
  See function <tt class="function">set_unittest_reportflags()</tt> below for
  a better way to set reporting options.

<P>
Optional argument <var>parser</var> specifies a <tt class="class">DocTestParser</tt> (or
  subclass) that should be used to extract tests from the files.  It
  defaults to a normal parser (i.e., <code><tt class="class">DocTestParser</tt>()</code>).

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1078' xml:id='l2h-1078' class="function">DocTestSuite</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>module</var><big>]</big><var></var><big>[</big><var>,
                              globs</var><big>]</big><var></var><big>[</big><var>, extraglobs</var><big>]</big><var></var><big>[</big><var>,
                              test_finder</var><big>]</big><var></var><big>[</big><var>, setUp</var><big>]</big><var></var><big>[</big><var>,
                              tearDown</var><big>]</big><var></var><big>[</big><var>, checker</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Convert doctest tests for a module to a
  <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt>.

<P>
The returned <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> is to be run by the
  unittest framework and runs each doctest in the module.  If any of the
  doctests fail, then the synthesized unit test fails, and a
  <tt class="exception">failureException</tt> exception is raised showing the name of the
  file containing the test and a (sometimes approximate) line number.

<P>
Optional argument <var>module</var> provides the module to be tested.  It
  can be a module object or a (possibly dotted) module name.  If not
  specified, the module calling this function is used.

<P>
Optional argument <var>globs</var> is a dictionary containing the
  initial global variables for the tests.  A new copy of this
  dictionary is created for each test.  By default, <var>globs</var> is
  a new empty dictionary.

<P>
Optional argument <var>extraglobs</var> specifies an extra set of
  global variables, which is merged into <var>globs</var>.  By default, no
  extra globals are used.

<P>
Optional argument <var>test_finder</var> is the <tt class="class">DocTestFinder</tt>
  object (or a drop-in replacement) that is used to extract doctests
  from the module.

<P>
Optional arguments <var>setUp</var>, <var>tearDown</var>, and <var>optionflags</var>
  are the same as for function <tt class="function">DocFileSuite()</tt> above.

<P>

<span class="versionnote">New in version 2.3.</span>

<P>

<span class="versionnote">Changed in version 2.4:
The parameters <var>globs</var>, <var>extraglobs</var>,
    <var>test_finder</var>, <var>setUp</var>, <var>tearDown</var>, and
    <var>optionflags</var> were added; this function now uses the same search
    technique as <tt class="function">testmod()</tt>.</span>

</dl>

<P>
Under the covers, <tt class="function">DocTestSuite()</tt> creates a
<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> out of <tt class="class">doctest.DocTestCase</tt>
instances, and <tt class="class">DocTestCase</tt> is a subclass of
<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestCase</tt>. <tt class="class">DocTestCase</tt> isn't documented
here (it's an internal detail), but studying its code can answer questions
about the exact details of <tt class="module"><a href="module-unittest.html">unittest</a></tt> integration.

<P>
Similarly, <tt class="function">DocFileSuite()</tt> creates a
<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> out of <tt class="class">doctest.DocFileCase</tt>
instances, and <tt class="class">DocFileCase</tt> is a subclass of <tt class="class">DocTestCase</tt>.

<P>
So both ways of creating a <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> run
instances of <tt class="class">DocTestCase</tt>.  This is important for a subtle reason:
when you run <tt class="module"><a href="module-doctest.html">doctest</a></tt> functions yourself, you can control the
<tt class="module"><a href="module-doctest.html">doctest</a></tt> options in use directly, by passing option flags to
<tt class="module"><a href="module-doctest.html">doctest</a></tt> functions.  However, if you're writing a
<tt class="module"><a href="module-unittest.html">unittest</a></tt> framework, <tt class="module"><a href="module-unittest.html">unittest</a></tt> ultimately controls
when and how tests get run.  The framework author typically wants to
control <tt class="module"><a href="module-doctest.html">doctest</a></tt> reporting options (perhaps, e.g., specified by
command line options), but there's no way to pass options through
<tt class="module"><a href="module-unittest.html">unittest</a></tt> to <tt class="module"><a href="module-doctest.html">doctest</a></tt> test runners.

<P>
For this reason, <tt class="module"><a href="module-doctest.html">doctest</a></tt> also supports a notion of
<tt class="module"><a href="module-doctest.html">doctest</a></tt> reporting flags specific to <tt class="module"><a href="module-unittest.html">unittest</a></tt>
support, via this function:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1079' xml:id='l2h-1079' class="function">set_unittest_reportflags</tt></b>(</nobr></td>
  <td><var>flags</var>)</td></tr></table></dt>
<dd>
  Set the <tt class="module"><a href="module-doctest.html">doctest</a></tt> reporting flags to use.

<P>
Argument <var>flags</var> or's together option flags.  See
  section&nbsp;<A href="doctest-options.html#doctest-options">5.2.3</A>.  Only "reporting flags" can be used.

<P>
This is a module-global setting, and affects all future doctests run by
  module <tt class="module"><a href="module-unittest.html">unittest</a></tt>:  the <tt class="method">runTest()</tt> method of
  <tt class="class">DocTestCase</tt> looks at the option flags specified for the test case
  when the <tt class="class">DocTestCase</tt> instance was constructed.  If no reporting
  flags were specified (which is the typical and expected case),
  <tt class="module"><a href="module-doctest.html">doctest</a></tt>'s <tt class="module"><a href="module-unittest.html">unittest</a></tt> reporting flags are or'ed into
  the option flags, and the option flags so augmented are passed to the
  <tt class="class">DocTestRunner</tt> instance created to run the doctest.  If any
  reporting flags were specified when the <tt class="class">DocTestCase</tt> instance was
  constructed, <tt class="module"><a href="module-doctest.html">doctest</a></tt>'s <tt class="module"><a href="module-unittest.html">unittest</a></tt> reporting flags
  are ignored.

<P>
The value of the <tt class="module"><a href="module-unittest.html">unittest</a></tt> reporting flags in effect before the
  function was called is returned by the function.

<P>

<span class="versionnote">New in version 2.4.</span>

</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.4 Basic API"
  href="doctest-basic-api.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 doctest  "
  href="module-doctest.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 Advanced API"
  href="doctest-advanced-api.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-basic-api.html">5.2.4 Basic API</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="doctest-advanced-api.html">5.2.6 Advanced API</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>