[Patches] [ python-Patches-732394 ] Docs for test package
SourceForge.net
noreply@sourceforge.net
Wed, 07 May 2003 15:07:15 -0700
Patches item #732394, was opened at 2003-05-04 19:09
Message generated for change (Comment added) made by nnorwitz
You can respond by visiting:
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=732394&group_id=5470
Category: Documentation
Group: Python 2.3
Status: Open
Resolution: Accepted
Priority: 5
Submitted By: Brett Cannon (bcannon)
Assigned to: Brett Cannon (bcannon)
Summary: Docs for test package
Initial Comment:
Here is an attempt to document the test package. I tried to explain
what the package is for, document test_support (but only things
relevant to unittest tests; no need to push older-style tests), how to
write a test for the package, and how to use regrtest.py (roughly).
The only thing I am not sure on is what the preferred way to execute
tests is anymore; is it run_suite or run_unittest from test_support?
Now that run_unittest takes in *classes should we be pushing that
since the code is shorter and less error-prone?
----------------------------------------------------------------------
>Comment By: Neal Norwitz (nnorwitz)
Date: 2003-05-07 18:07
Message:
Logged In: YES
user_id=33168
Doesn't doc/Makefile.deps need to be updated too?
----------------------------------------------------------------------
Comment By: Brett Cannon (bcannon)
Date: 2003-05-07 18:02
Message:
Logged In: YES
user_id=357491
Both are checked in. Want me to leave this patch open to remind you to take
a look, Fred? Or should I go ahead and close it?
----------------------------------------------------------------------
Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2003-05-07 11:21
Message:
Logged In: YES
user_id=3066
Looks like LaTeX to me. This'll be easier to work with once
it's in CVS, so go ahead and commit.
Thanks!
----------------------------------------------------------------------
Comment By: Brett Cannon (bcannon)
Date: 2003-05-06 20:31
Message:
Logged In: YES
user_id=357491
Bah. This has not been my day at all.
----------------------------------------------------------------------
Comment By: Raymond Hettinger (rhettinger)
Date: 2003-05-06 20:01
Message:
Logged In: YES
user_id=80475
The previous version got deleted but newer one did not
take its place. The upload may have failed.
----------------------------------------------------------------------
Comment By: Brett Cannon (bcannon)
Date: 2003-05-06 16:26
Message:
Logged In: YES
user_id=357491
First, thanks to both Raymond and Walter for looking for this.
Second, I fixed everything both of them brought up sans merging Lib/test/
README into the doc as Walter suggested (read below for an explanation on
why).
Third, I don't want to merge in Lib/test/README since this is meant to
replace it. I tried to use it as a guide to make sure everything in there gets
covered in here (which is why there is a section on how to write a good
regression test).
Fourth, I will assign it to Fred but not check it in until he gets a chance to
look at it and tells me to check it in. I will thus not touch lib.tex unless Fred
tells me to.
----------------------------------------------------------------------
Comment By: Walter Dörwald (doerwalter)
Date: 2003-05-06 07:17
Message:
Logged In: YES
user_id=89016
A few other problems:
Line 247: "Specifying a single regression", this should show
how the call to regrtest looks like.
Line 254: "turns enables" -> "enables"
Line 257: "common-separated" -> "comma-separated"
I think the description of black box testing and white box
testing is reversed. (Compare Lib/test/README). Maybe we
should combine both texts (libtest.tex and Lib/test/README)?
----------------------------------------------------------------------
Comment By: Raymond Hettinger (rhettinger)
Date: 2003-05-06 04:38
Message:
Logged In: YES
user_id=80475
This is a good looking document.
Here are a few nits:
---------------------------
line 23: [replace] "traditional" [with] ``traditional''
line 29: [add] \end{seealso}
line 61: [replace] True [with] \constant{True}
line 68: [replace] True [with] \constant{True}
line 72: [replace] True [with] \constant{True}
line 109: [consider noting the classes are broken into
individual testcases using the rules for MakeSuite.
Technically, the class itself is not executed. The test
runner scans for methodnames starting with "test" and
builds a suite of testcases.]
line 190: [replace] bering [with] being
line 191: [replace parenthetical with] testing only the
published user interface
line 215: [replace my error] self.func [with] func
line 217: [eliminate my extraneous space before the open
parenthesis]
line 231: [delete]
line 233: [delete]
After fixing those, go ahead a load it or assign it to Fred for
further review (he does that anyway).
Then, add libtest.tex to lib.tex so it will appear in the index
and become part of the build.
----------------------------------------------------------------------
Comment By: Brett Cannon (bcannon)
Date: 2003-05-06 04:03
Message:
Logged In: YES
user_id=357491
OK, following Raymond's suggestions, here is revised version of the docs. I
tried to be terse and concrete, but it goes against my personal writing style (I
used to get marked off for this when my philosophy classes because I
refused to write dry papers; still haven't learned my lesson =).
----------------------------------------------------------------------
Comment By: Raymond Hettinger (rhettinger)
Date: 2003-05-06 02:46
Message:
Logged In: YES
user_id=80475
Well, it does have an air of near perfection ;) The content,
accuracy, and completeness are ten times more
important than the form :-)
Most of the stuff is just a one element change. The
abbreviations are just a style manual thing. When you
write your second set of docs almost none of this will
come up.
Things like section markers and seealso's are pretty easy.
The trick is to write docs by pasting in snippet's from other
docs. I always find the nearest match (in form, not
content) and keep it open while writing the docs.
The attached script may help. It catches the kind of TeX
errors that I tend to make. BTW, the hard knocks
document may have understated this one a bit.
----------------------------------------------------------------------
Comment By: Brett Cannon (bcannon)
Date: 2003-05-06 01:43
Message:
Logged In: YES
user_id=357491
Ah nuts, Raymond. You were supposed to say it was perfect. =)
OK, I will make the fixes and clean up the text to be more terse and sterile.
So this is why people hate writing docs...
----------------------------------------------------------------------
Comment By: Raymond Hettinger (rhettinger)
Date: 2003-05-05 19:31
Message:
Logged In: YES
user_id=80475
The \section title should indicate that the regression tests
are for python itself.
Add a seealso note referencing unittest and doctest.
On line 78, \dict{sys.modules} should be \module
{sys.modules}.
On line 123, remove the exclamation point and explain the
guideline rationale (docstrings get printed out, but
comments don't).
On line 194, add a closing parenthesis.
On line 226, \Windows{} should be Windows.
In either the guidelines section or the example section,
show how common code can be factored out through
subclassing (this question comes-up alot):
class TestFuncAcceptsSequences(unittest.TestCase):
self.func = mySuperWhammyFunction
def test_func(self):
self.func (self.arg)
class AcceptLists(TestFuncAcceptsSequences):
arg = [1,2,3]
class AcceptStrings(TestFuncAcceptsSequences):
arg = 'abc'
class AcceptTuples(TestFuncAcceptsSequences):
arg = (1,2,3)
Everywhere. Do not use abbreviations like e.g., i.e. and
etc. They do not transate well and Fred will come in
behind you and remove them all.
Change the voice to not speak directly to the reader. None
of this: "you will most likely not use these modules
directly". Instead try: "Except for test_support.py, most of
these modules are not needed by user code".
New tests do not *have to be* in unittest format. Instead,
mention that the unittest format is more flexible and
easier to extend for future maintainers.
At the end, refer readers to Kent Beck's Test-Driven
Development for more guidelines.
Try to tighten-up the sentence structure to be much more
terse and concrete. Avoid vague "recommended"
or "prohibited" talk, instead giving fact based advantages
and disadvantages.
Consider a three or four part grouping:
* First, collect all of the prose into one intro section.
* Put the function/method description one section.
* Put the examples/boilerplate in another.
* Final collect the guidelines in a separate section.
See libsets.tex and libitertools.tex to see how it's done and
what it looks like.
----------------------------------------------------------------------
Comment By: Raymond Hettinger (rhettinger)
Date: 2003-05-05 18:33
Message:
Logged In: YES
user_id=80475
Yes, run_unittest(*classes) is the most general and
requires the least boilerplate.
Will read through your docs tonight. Thanks for
the effort to take this beyond (read the code to
figure out what it does).
----------------------------------------------------------------------
You can respond by visiting:
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=732394&group_id=5470