[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / 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>
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="prev" href="doctest-debugging.html" />
	13	<link rel="parent" href="module-doctest.html" />
	14	<link rel="next" href="module-unittest.html" />
	15	<meta name='aesop' content='information' />
	16	<title>5.2.8 Soapbox</title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="5.2.7 Debugging"
	24	href="doctest-debugging.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="5.2 doctest "
	27	href="module-doctest.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="5.3 unittest "
	30	href="module-unittest.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Python Library Reference</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	37	border='0' height='32' alt='Module Index' width='32' /></a></td>
	38	<td class='online-navigation'><a rel="index" title="Index"
	39	href="genindex.html"><img src='../icons/index.png'
	40	border='0' height='32' alt='Index' width='32' /></A></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="doctest-debugging.html">5.2.7 Debugging</A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest </A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="module-unittest.html">5.3 unittest </A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H2><A NAME="SECTION007280000000000000000"></A><A NAME="doctest-soapbox"></A>
	55	<BR>
	56	5.2.8 Soapbox
	57	</H2>
	58
	59	<P>
	60	As mentioned in the introduction, <tt class="module"><a href="module-doctest.html">doctest</a></tt> has grown to have
	61	three primary uses:
	62
	63	<P>
	64
65	<OL>
66	<LI>Checking examples in docstrings.
67	</LI>
68	<LI>Regression testing.
69	</LI>
70	<LI>Executable documentation / literate testing.
71	</LI>
72	</OL>
73
74	<P>
75	These uses have different requirements, and it is important to
76	distinguish them. In particular, filling your docstrings with obscure
77	test cases makes for bad documentation.
78
79	<P>
80	When writing a docstring, choose docstring examples with care.
81	There's an art to this that needs to be learned--it may not be
82	natural at first. Examples should add genuine value to the
83	documentation. A good example can often be worth many words.
84	If done with care, the examples will be invaluable for your users, and
85	will pay back the time it takes to collect them many times over as the
86	years go by and things change. I'm still amazed at how often one of
87	my <tt class="module"><a href="module-doctest.html">doctest</a></tt> examples stops working after a "harmless"
88	change.
89
90	<P>
91	Doctest also makes an excellent tool for regression testing, especially if
92	you don't skimp on explanatory text. By interleaving prose and examples,
93	it becomes much easier to keep track of what's actually being tested, and
94	why. When a test fails, good prose can make it much easier to figure out
95	what the problem is, and how it should be fixed. It's true that you could
96	write extensive comments in code-based testing, but few programmers do.
97	Many have found that using doctest approaches instead leads to much clearer
98	tests. Perhaps this is simply because doctest makes writing prose a little
99	easier than writing code, while writing comments in code is a little
100	harder. I think it goes deeper than just that: the natural attitude
101	when writing a doctest-based test is that you want to explain the fine
102	points of your software, and illustrate them with examples. This in
103	turn naturally leads to test files that start with the simplest features,
104	and logically progress to complications and edge cases. A coherent
105	narrative is the result, instead of a collection of isolated functions
106	that test isolated bits of functionality seemingly at random. It's
107	a different attitude, and produces different results, blurring the
108	distinction between testing and explaining.
109
110	<P>
111	Regression testing is best confined to dedicated objects or files. There
112	are several options for organizing tests:
113
114	<P>
115
116	<UL>
117	<LI>Write text files containing test cases as interactive examples,
118	and test the files using <tt class="function">testfile()</tt> or
119	<tt class="function">DocFileSuite()</tt>. This is recommended, although is
120	easiest to do for new projects, designed from the start to use
121	doctest.
122	</LI>
123	<LI>Define functions named <code>_regrtest_<i>topic</i></code> that
124	consist of single docstrings, containing test cases for the
125	named topics. These functions can be included in the same file
126	as the module, or separated out into a separate test file.
127	</LI>
128	<LI>Define a <code>__test__</code> dictionary mapping from regression test
129	topics to docstrings containing test cases.
130	</LI>
131	</UL>
132
133	<DIV CLASS="navigation">
134	<div class='online-navigation'>
135	<p></p><hr />
136	<table align="center" width="100%" cellpadding="0" cellspacing="2">
137	<tr>
138	<td class='online-navigation'><a rel="prev" title="5.2.7 Debugging"
139	href="doctest-debugging.html"><img src='../icons/previous.png'
140	border='0' height='32' alt='Previous Page' width='32' /></A></td>
141	<td class='online-navigation'><a rel="parent" title="5.2 doctest "
142	href="module-doctest.html"><img src='../icons/up.png'
143	border='0' height='32' alt='Up One Level' width='32' /></A></td>
144	<td class='online-navigation'><a rel="next" title="5.3 unittest "
145	href="module-unittest.html"><img src='../icons/next.png'
146	border='0' height='32' alt='Next Page' width='32' /></A></td>
147	<td align="center" width="100%">Python Library Reference</td>
148	<td class='online-navigation'><a rel="contents" title="Table of Contents"
149	href="contents.html"><img src='../icons/contents.png'
150	border='0' height='32' alt='Contents' width='32' /></A></td>
151	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
152	border='0' height='32' alt='Module Index' width='32' /></a></td>
153	<td class='online-navigation'><a rel="index" title="Index"
154	href="genindex.html"><img src='../icons/index.png'
155	border='0' height='32' alt='Index' width='32' /></A></td>
156	</tr></table>
157	<div class='online-navigation'>
158	<b class="navlabel">Previous:</b>
159	<a class="sectref" rel="prev" href="doctest-debugging.html">5.2.7 Debugging</A>
160	<b class="navlabel">Up:</b>
161	<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest </A>
162	<b class="navlabel">Next:</b>
163	<a class="sectref" rel="next" href="module-unittest.html">5.3 unittest </A>
164	</div>
165	</div>
166	<hr />
167	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
168	</DIV>
169	<!--End of Navigation Panel-->
170	<ADDRESS>
171	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
172	</ADDRESS>
173	</BODY>
174	</HTML>