[Patches] [ python-Patches-732394 ] Docs for test package

Sun, 11 May 2003 16:26:04 -0700

Patches item #732394, was opened at 2003-05-04 16:09
Message generated for change (Comment added) made by bcannon
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: Closed
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: Brett Cannon (bcannon)
Date: 2003-05-11 16:26

Message:
Logged In: YES 
user_id=357491

Since I uploaded the new files, tweaked Makefile.deps, and Fred has already 
taken at least one pass at fiddling with the file I am going to close this patch.

----------------------------------------------------------------------

Comment By: Neal Norwitz (nnorwitz)
Date: 2003-05-07 15: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 15: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 08: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 17: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 17: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 13: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 04: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 01: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 01: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-05 23: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-05 22: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 16: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 15: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