Issue 732394: Docs for test package (original) (raw)

Created on 2003-05-04 23:09 by brett.cannon, last changed 2022-04-10 16:08 by admin. This issue is now closed.

Messages (15)
msg43638 - (view)	Author: Brett Cannon (brett.cannon) *	Date: 2003-05-04 23:09
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?
msg43639 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2003-05-05 22:33
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).
msg43640 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2003-05-05 23:31
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.
msg43641 - (view)	Author: Brett Cannon (brett.cannon) *	Date: 2003-05-06 05:43
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...
msg43642 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2003-05-06 06:46
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.
msg43643 - (view)	Author: Brett Cannon (brett.cannon) *	Date: 2003-05-06 08:03
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 =).
msg43644 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2003-05-06 08:38
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.
msg43645 - (view)	Author: Walter Dörwald (doerwalter) *	Date: 2003-05-06 11:17
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)?
msg43646 - (view)	Author: Brett Cannon (brett.cannon) *	Date: 2003-05-06 20:26
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.
msg43647 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2003-05-07 00:01
Logged In: YES user_id=80475 The previous version got deleted but newer one did not take its place. The upload may have failed.
msg43648 - (view)	Author: Brett Cannon (brett.cannon) *	Date: 2003-05-07 00:31
Logged In: YES user_id=357491 Bah. This has not been my day at all.
msg43649 - (view)	Author: Fred Drake (fdrake)	Date: 2003-05-07 15:21
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!
msg43650 - (view)	Author: Brett Cannon (brett.cannon) *	Date: 2003-05-07 22:02
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?
msg43651 - (view)	Author: Neal Norwitz (nnorwitz) *	Date: 2003-05-07 22:07
Logged In: YES user_id=33168 Doesn't doc/Makefile.deps need to be updated too?
msg43652 - (view)	Author: Brett Cannon (brett.cannon) *	Date: 2003-05-11 23:26
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.