sam-t2/devtools/amd64/html/python/lib/doctest-soapbox.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="prev" href="doctest-debugging.html" />
<link rel="parent" href="module-doctest.html" />
<link rel="next" href="module-unittest.html" />
<meta name='aesop' content='information' />
<title>5.2.8 Soapbox</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.7 Debugging"
  href="doctest-debugging.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.3 unittest  "
  href="module-unittest.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-debugging.html">5.2.7 Debugging</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="module-unittest.html">5.3 unittest  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION007280000000000000000"></A><A NAME="doctest-soapbox"></A>
<BR>
5.2.8 Soapbox
</H2>

<P>
As mentioned in the introduction, <tt class="module"><a href="module-doctest.html">doctest</a></tt> has grown to have
three primary uses:

<P>

<OL>
<LI>Checking examples in docstrings.
</LI>
<LI>Regression testing.
</LI>
<LI>Executable documentation / literate testing.
</LI>
</OL>

<P>
These uses have different requirements, and it is important to
distinguish them.  In particular, filling your docstrings with obscure
test cases makes for bad documentation.

<P>
When writing a docstring, choose docstring examples with care.
There's an art to this that needs to be learned--it may not be
natural at first.  Examples should add genuine value to the
documentation.  A good example can often be worth many words.
If done with care, the examples will be invaluable for your users, and
will pay back the time it takes to collect them many times over as the
years go by and things change.  I'm still amazed at how often one of
my <tt class="module"><a href="module-doctest.html">doctest</a></tt> examples stops working after a "harmless"
change.

<P>
Doctest also makes an excellent tool for regression testing, especially if
you don't skimp on explanatory text.  By interleaving prose and examples,
it becomes much easier to keep track of what's actually being tested, and
why.  When a test fails, good prose can make it much easier to figure out
what the problem is, and how it should be fixed.  It's true that you could
write extensive comments in code-based testing, but few programmers do.
Many have found that using doctest approaches instead leads to much clearer
tests.  Perhaps this is simply because doctest makes writing prose a little
easier than writing code, while writing comments in code is a little
harder.  I think it goes deeper than just that:  the natural attitude
when writing a doctest-based test is that you want to explain the fine
points of your software, and illustrate them with examples.  This in
turn naturally leads to test files that start with the simplest features,
and logically progress to complications and edge cases.  A coherent
narrative is the result, instead of a collection of isolated functions
that test isolated bits of functionality seemingly at random.  It's
a different attitude, and produces different results, blurring the
distinction between testing and explaining.

<P>
Regression testing is best confined to dedicated objects or files.  There
are several options for organizing tests:

<P>

<UL>
<LI>Write text files containing test cases as interactive examples,
      and test the files using <tt class="function">testfile()</tt> or
      <tt class="function">DocFileSuite()</tt>.  This is recommended, although is
      easiest to do for new projects, designed from the start to use
      doctest.
</LI>
<LI>Define functions named <code>_regrtest_<i>topic</i></code> that
      consist of single docstrings, containing test cases for the
      named topics.  These functions can be included in the same file
      as the module, or separated out into a separate test file.
</LI>
<LI>Define a <code>__test__</code> dictionary mapping from regression test
      topics to docstrings containing test cases.
</LI>
</UL>

<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.7 Debugging"
  href="doctest-debugging.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.3 unittest  "
  href="module-unittest.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-debugging.html">5.2.7 Debugging</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="module-unittest.html">5.3 unittest  </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>