[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / 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>
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="doctest-advanced-api.html" />
	13	<link rel="prev" href="doctest-basic-api.html" />
	14	<link rel="parent" href="module-doctest.html" />
	15	<link rel="next" href="doctest-advanced-api.html" />
	16	<meta name='aesop' content='information' />
	17	<title>5.2.5 Unittest API</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.4 Basic API"
	25	href="doctest-basic-api.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 doctest "
	28	href="module-doctest.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 Advanced API"
	31	href="doctest-advanced-api.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-basic-api.html">5.2.4 Basic API</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="doctest-advanced-api.html">5.2.6 Advanced API</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION007250000000000000000"></A><A NAME="doctest-unittest-api"></A>
	56	<BR>
	57	5.2.5 Unittest API
	58	</H2>
	59
	60	<P>
	61	As your collection of doctest'ed modules grows, you'll want a way to run
	62	all their doctests systematically. Prior to Python 2.4, <tt class="module"><a href="module-doctest.html">doctest</a></tt>
	63	had a barely documented <tt class="class">Tester</tt> class that supplied a rudimentary
	64	way to combine doctests from multiple modules. <tt class="class">Tester</tt> was feeble,
65	and in practice most serious Python testing frameworks build on the
66	<tt class="module"><a href="module-unittest.html">unittest</a></tt> module, which supplies many flexible ways to combine
67	tests from multiple sources. So, in Python 2.4, <tt class="module"><a href="module-doctest.html">doctest</a></tt>'s
68	<tt class="class">Tester</tt> class is deprecated, and <tt class="module"><a href="module-doctest.html">doctest</a></tt> provides two
69	functions that can be used to create <tt class="module"><a href="module-unittest.html">unittest</a></tt> test suites from
70	modules and text files containing doctests. These test suites can then be
71	run using <tt class="module"><a href="module-unittest.html">unittest</a></tt> test runners:
72
73	<P>
74	<div class="verbatim"><pre>
75	import unittest
76	import doctest
77	import my_module_with_doctests, and_another
78
79	suite = unittest.TestSuite()
80	for mod in my_module_with_doctests, and_another:
81	suite.addTest(doctest.DocTestSuite(mod))
82	runner = unittest.TextTestRunner()
83	runner.run(suite)
84	</pre></div>
85
86	<P>
87	There are two main functions for creating <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt>
88	instances from text files and modules with doctests:
89
90	<P>
91	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
92	<td><nobr><b><tt id='l2h-1077' xml:id='l2h-1077' class="function">DocFileSuite</tt></b>(</nobr></td>
93	<td><var>paths, *kw</var>)</td></tr></table></dt>
94	<dd>
95	Convert doctest tests from one or more text files to a
96	<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt>.
97
98	<P>
99	The returned <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> is to be run by the
100	unittest framework and runs the interactive examples in each file. If an
101	example in any file fails, then the synthesized unit test fails, and a
102	<tt class="exception">failureException</tt> exception is raised showing the name of the
103	file containing the test and a (sometimes approximate) line number.
104
105	<P>
106	Pass one or more paths (as strings) to text files to be examined.
107
108	<P>
109	Options may be provided as keyword arguments:
110
111	<P>
112	Optional argument <var>module_relative</var> specifies how
113	the filenames in <var>paths</var> should be interpreted:
114
115	<P>
116
117	<UL>
118	<LI>If <var>module_relative</var> is <code>True</code> (the default), then
119	each filename specifies an OS-independent module-relative
120	path. By default, this path is relative to the calling
121	module's directory; but if the <var>package</var> argument is
122	specified, then it is relative to that package. To ensure
123	OS-independence, each filename should use <code>/</code> characters
124	to separate path segments, and may not be an absolute path
125	(i.e., it may not begin with <code>/</code>).
126	</LI>
127	<LI>If <var>module_relative</var> is <code>False</code>, then each filename
128	specifies an OS-specific path. The path may be absolute or
129	relative; relative paths are resolved with respect to the
130	current working directory.
131
132	</LI>
133	</UL>
134
135	<P>
136	Optional argument <var>package</var> is a Python package or the name
137	of a Python package whose directory should be used as the base
138	directory for module-relative filenames. If no package is
139	specified, then the calling module's directory is used as the base
140	directory for module-relative filenames. It is an error to specify
141	<var>package</var> if <var>module_relative</var> is <code>False</code>.
142
143	<P>
144	Optional argument <var>setUp</var> specifies a set-up function for
145	the test suite. This is called before running the tests in each
146	file. The <var>setUp</var> function will be passed a <tt class="class">DocTest</tt>
147	object. The setUp function can access the test globals as the
148	<var>globs</var> attribute of the test passed.
149
150	<P>
151	Optional argument <var>tearDown</var> specifies a tear-down function
152	for the test suite. This is called after running the tests in each
153	file. The <var>tearDown</var> function will be passed a <tt class="class">DocTest</tt>
154	object. The setUp function can access the test globals as the
155	<var>globs</var> attribute of the test passed.
156
157	<P>
158	Optional argument <var>globs</var> is a dictionary containing the
159	initial global variables for the tests. A new copy of this
160	dictionary is created for each test. By default, <var>globs</var> is
161	a new empty dictionary.
162
163	<P>
164	Optional argument <var>optionflags</var> specifies the default
165	doctest options for the tests, created by or-ing together
166	individual option flags. See section <A href="doctest-options.html#doctest-options">5.2.3</A>.
167	See function <tt class="function">set_unittest_reportflags()</tt> below for
168	a better way to set reporting options.
169
170	<P>
171	Optional argument <var>parser</var> specifies a <tt class="class">DocTestParser</tt> (or
172	subclass) that should be used to extract tests from the files. It
173	defaults to a normal parser (i.e., <code><tt class="class">DocTestParser</tt>()</code>).
174
175	<P>
176
177	<span class="versionnote">New in version 2.4.</span>
178
179	</dl>
180
181	<P>
182	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
183	<td><nobr><b><tt id='l2h-1078' xml:id='l2h-1078' class="function">DocTestSuite</tt></b>(</nobr></td>
184	<td><var></var><big>[</big><var>module</var><big>]</big><var></var><big>[</big><var>,
185	globs</var><big>]</big><var></var><big>[</big><var>, extraglobs</var><big>]</big><var></var><big>[</big><var>,
186	test_finder</var><big>]</big><var></var><big>[</big><var>, setUp</var><big>]</big><var></var><big>[</big><var>,
187	tearDown</var><big>]</big><var></var><big>[</big><var>, checker</var><big>]</big><var></var>)</td></tr></table></dt>
188	<dd>
189	Convert doctest tests for a module to a
190	<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt>.
191
192	<P>
193	The returned <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> is to be run by the
194	unittest framework and runs each doctest in the module. If any of the
195	doctests fail, then the synthesized unit test fails, and a
196	<tt class="exception">failureException</tt> exception is raised showing the name of the
197	file containing the test and a (sometimes approximate) line number.
198
199	<P>
200	Optional argument <var>module</var> provides the module to be tested. It
201	can be a module object or a (possibly dotted) module name. If not
202	specified, the module calling this function is used.
203
204	<P>
205	Optional argument <var>globs</var> is a dictionary containing the
206	initial global variables for the tests. A new copy of this
207	dictionary is created for each test. By default, <var>globs</var> is
208	a new empty dictionary.
209
210	<P>
211	Optional argument <var>extraglobs</var> specifies an extra set of
212	global variables, which is merged into <var>globs</var>. By default, no
213	extra globals are used.
214
215	<P>
216	Optional argument <var>test_finder</var> is the <tt class="class">DocTestFinder</tt>
217	object (or a drop-in replacement) that is used to extract doctests
218	from the module.
219
220	<P>
221	Optional arguments <var>setUp</var>, <var>tearDown</var>, and <var>optionflags</var>
222	are the same as for function <tt class="function">DocFileSuite()</tt> above.
223
224	<P>
225
226	<span class="versionnote">New in version 2.3.</span>
227
228	<P>
229
230	<span class="versionnote">Changed in version 2.4:
231	The parameters <var>globs</var>, <var>extraglobs</var>,
232	<var>test_finder</var>, <var>setUp</var>, <var>tearDown</var>, and
233	<var>optionflags</var> were added; this function now uses the same search
234	technique as <tt class="function">testmod()</tt>.</span>
235
236	</dl>
237
238	<P>
239	Under the covers, <tt class="function">DocTestSuite()</tt> creates a
240	<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> out of <tt class="class">doctest.DocTestCase</tt>
241	instances, and <tt class="class">DocTestCase</tt> is a subclass of
242	<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestCase</tt>. <tt class="class">DocTestCase</tt> isn't documented
243	here (it's an internal detail), but studying its code can answer questions
244	about the exact details of <tt class="module"><a href="module-unittest.html">unittest</a></tt> integration.
245
246	<P>
247	Similarly, <tt class="function">DocFileSuite()</tt> creates a
248	<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> out of <tt class="class">doctest.DocFileCase</tt>
249	instances, and <tt class="class">DocFileCase</tt> is a subclass of <tt class="class">DocTestCase</tt>.
250
251	<P>
252	So both ways of creating a <tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestSuite</tt> run
253	instances of <tt class="class">DocTestCase</tt>. This is important for a subtle reason:
254	when you run <tt class="module"><a href="module-doctest.html">doctest</a></tt> functions yourself, you can control the
255	<tt class="module"><a href="module-doctest.html">doctest</a></tt> options in use directly, by passing option flags to
256	<tt class="module"><a href="module-doctest.html">doctest</a></tt> functions. However, if you're writing a
257	<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
258	when and how tests get run. The framework author typically wants to
259	control <tt class="module"><a href="module-doctest.html">doctest</a></tt> reporting options (perhaps, e.g., specified by
260	command line options), but there's no way to pass options through
261	<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.
262
263	<P>
264	For this reason, <tt class="module"><a href="module-doctest.html">doctest</a></tt> also supports a notion of
265	<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>
266	support, via this function:
267
268	<P>
269	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
270	<td><nobr><b><tt id='l2h-1079' xml:id='l2h-1079' class="function">set_unittest_reportflags</tt></b>(</nobr></td>
271	<td><var>flags</var>)</td></tr></table></dt>
272	<dd>
273	Set the <tt class="module"><a href="module-doctest.html">doctest</a></tt> reporting flags to use.
274
275	<P>
276	Argument <var>flags</var> or's together option flags. See
277	section <A href="doctest-options.html#doctest-options">5.2.3</A>. Only "reporting flags" can be used.
278
279	<P>
280	This is a module-global setting, and affects all future doctests run by
281	module <tt class="module"><a href="module-unittest.html">unittest</a></tt>: the <tt class="method">runTest()</tt> method of
282	<tt class="class">DocTestCase</tt> looks at the option flags specified for the test case
283	when the <tt class="class">DocTestCase</tt> instance was constructed. If no reporting
284	flags were specified (which is the typical and expected case),
285	<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
286	the option flags, and the option flags so augmented are passed to the
287	<tt class="class">DocTestRunner</tt> instance created to run the doctest. If any
288	reporting flags were specified when the <tt class="class">DocTestCase</tt> instance was
289	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
290	are ignored.
291
292	<P>
293	The value of the <tt class="module"><a href="module-unittest.html">unittest</a></tt> reporting flags in effect before the
294	function was called is returned by the function.
295
296	<P>
297
298	<span class="versionnote">New in version 2.4.</span>
299
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.2.4 Basic API"
310	href="doctest-basic-api.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.2 doctest "
313	href="module-doctest.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.2.6 Advanced API"
316	href="doctest-advanced-api.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="doctest-basic-api.html">5.2.4 Basic API</A>
331	<b class="navlabel">Up:</b>
332	<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest </A>
333	<b class="navlabel">Next:</b>
334	<a class="sectref" rel="next" href="doctest-advanced-api.html">5.2.6 Advanced API</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>