diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | doc/dde.n | 4 | ||||
| -rw-r--r-- | doc/http.n | 6 | ||||
| -rw-r--r-- | doc/msgcat.n | 2 | ||||
| -rw-r--r-- | doc/registry.n | 4 | ||||
| -rw-r--r-- | doc/tcltest.n | 167 |
6 files changed, 90 insertions, 99 deletions
@@ -1,5 +1,11 @@ 2002-06-27 Don Porter <dgp@users.sourceforge.net> + * doc/dde.n: Work in progress updating the documentation + * doc/http.n: of the packages that come bundled with + * doc/msgcat.n: the Tcl source distribution, notably tcltest. + * doc/registry.n: + * doc/tcltest.n: + * library/tcltest/tcltest.tcl: Made sure that the TCLTEST_OPTIONS environment variablle configures tcltest at package load time. @@ -5,10 +5,10 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: dde.n,v 1.7 2001/08/22 23:56:14 hobbs Exp $ +'\" RCS: @(#) $Id: dde.n,v 1.8 2002/06/27 22:29:08 dgp Exp $ '\" .so man.macros -.TH dde n 8.4 Tcl "Tcl Built-In Commands" +.TH dde n 1.2 dde "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -5,14 +5,14 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: http.n,v 1.15 2002/04/18 16:46:24 dgp Exp $ +'\" RCS: @(#) $Id: http.n,v 1.16 2002/06/27 22:29:08 dgp Exp $ '\" .so man.macros -.TH "Http" n 8.3 Tcl "Tcl Built-In Commands" +.TH "http" n 2.4 http "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Http \- Client-side implementation of the HTTP/1.0 protocol. +http \- Client-side implementation of the HTTP/1.0 protocol. .SH SYNOPSIS \fBpackage require http ?2.4?\fR .sp diff --git a/doc/msgcat.n b/doc/msgcat.n index 614c2b5..cba5a45 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -7,7 +7,7 @@ '\" SCCS: @(#) msgcat.n '\" .so man.macros -.TH "msgcat" n 8.1 Tcl "Tcl Built-In Commands" +.TH "msgcat" n 1.3 msgcat "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME diff --git a/doc/registry.n b/doc/registry.n index f0e199f..cfb5ca2 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -4,10 +4,10 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: registry.n,v 1.4 1999/04/16 00:46:35 stanton Exp $ +'\" RCS: @(#) $Id: registry.n,v 1.5 2002/06/27 22:29:08 dgp Exp $ '\" .so man.macros -.TH registry n 8.0 Tcl "Tcl Built-In Commands" +.TH registry n 1.0 registry "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME diff --git a/doc/tcltest.n b/doc/tcltest.n index e4009bd..955f2eb 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -3,98 +3,83 @@ '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" Copyright (c) 1998-1999 Scriptics Corporation '\" Copyright (c) 2000 Ajuba Solutions +'\" Contributions from Don Porter, NIST, 2002. (not subject to US copyright) '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tcltest.n,v 1.19 2002/06/06 20:54:03 dgp Exp $ +'\" RCS: @(#) $Id: tcltest.n,v 1.20 2002/06/27 22:29:08 dgp Exp $ '\" .so man.macros -.TH "tcltest" n 8.4 Tcl "Tcl Built-In Commands" +.TH "tcltest" n 2.1 tcltest "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME tcltest \- Test harness support code and utilities .SH SYNOPSIS +.nf \fBpackage require tcltest ?2.1?\fR .sp \fBtcltest::test \fIname desc ?option value? ?option value? ...\fR -.br +\fBtcltest::test \fIname desc constraints body result\fR \fBtcltest::test \fIname desc {?option value? ?option value? ...}\fR .sp +\fBtcltest::makeDirectory \fIname ?directory?\fR +\fBtcltest::removeDirectory \fIname ?directory?\fR +\fBtcltest::makeFile \fIcontents name ?directory?\fR +\fBtcltest::removeFile \fIname ?directory?\fR +\fBtcltest::viewFile \fIname ?directory?\fR +\fBtcltest::loadTestedCommands\fR \fBtcltest::cleanupTests \fI?runningMultipleTests?\fR -.sp \fBtcltest::runAllTests\fR .sp +.VS 2.1 +\fBtcltest::configure \fI?option? ?value option value ...?\fR +.VE +\fBtcltest::testConstraint \fIconstraint ?value?\fR +.VS 2.1 +\fBtcltest::customMatch \fImode command\fR +.VE +\fBtcltest::outputChannel \fI?channelID?\fR +\fBtcltest::errorChannel \fI?channelID?\fR \fBtcltest::interpreter \fI?interp?\fR .sp -\fBtcltest::singleProcess \fI?value?\fR -.sp \fBtcltest::debug \fI?level?\fR -.sp -\fBtcltest::verbose \fI?levelList?\fR -.sp -\fBtcltest::preserveCore \fI?level?\fR -.sp -\fBtcltest::customMatch \fImode command\fR -.sp -\fBtcltest::testConstraint \fIconstraint ?value?\fR -.sp +\fBtcltest::errorFile \fI?filename?\fR \fBtcltest::limitConstraints \fI?value?\fR -.sp -\fBtcltest::workingDirectory \fI?dir?\fR -.sp -\fBtcltest::temporaryDirectory \fI?dir?\fR -.sp -\fBtcltest::testsDirectory \fI?dir?\fR -.sp +\fBtcltest::loadFile \fI?filename?\fR +\fBtcltest::loadScript \fI?script?\fR \fBtcltest::match \fI?patternList?\fR -.sp -\fBtcltest::matchFiles \fI?patternList?\fR -.sp \fBtcltest::matchDirectories \fI?patternList?\fR -.sp +\fBtcltest::matchFiles \fI?patternList?\fR +\fBtcltest::outputFile \fI?filename?\fR +\fBtcltest::preserveCore \fI?level?\fR +\fBtcltest::singleProcess \fI?value?\fR \fBtcltest::skip \fI?patternList?\fR -.sp -\fBtcltest::skipFiles \fI?patternList?\fR -.sp \fBtcltest::skipDirectories \fI?patternList?\fR +\fBtcltest::skipFiles \fI?patternList?\fR +\fBtcltest::temporaryDirectory \fI?dir?\fR +\fBtcltest::testsDirectory \fI?dir?\fR +\fBtcltest::verbose \fI?levelList?\fR .sp -\fBtcltest::loadTestedCommands\fR -.sp -\fBtcltest::loadScript \fI?script?\fR -.sp -\fBtcltest::loadFile \fI?filename?\fR -.sp -\fBtcltest::outputChannel \fI?channelID?\fR -.sp -\fBtcltest::outputFile \fI?filename?\fR -.sp -\fBtcltest::errorChannel \fI?channelID?\fR -.sp -\fBtcltest::errorFile \fI?filename?\fR -.sp -\fBtcltest::makeFile \fIcontents name ?directory?\fR -.sp -\fBtcltest::removeFile \fIname ?directory?\fR -.sp -\fBtcltest::makeDirectory \fIname ?directory?\fR -.sp -\fBtcltest::removeDirectory \fIname ?directory?\fR -.sp -\fBtcltest::viewFile \fIname ?directory?\fR -.sp +\fBtcltest::bytestring \fIstring\fR \fBtcltest::normalizeMsg \fImsg\fR -.sp \fBtcltest::normalizePath \fIpathVar\fR -.sp -\fBtcltest::bytestring \fIstring\fR +\fBtcltest::workingDirectory \fI?dir?\fR +.fi .BE .SH DESCRIPTION .PP -The \fBtcltest\fR package provides the user with utility tools for -writing and running tests in the Tcl test suite. It can also be used -to create a customized test harness for an extension. +The \fBtcltest\fR package provides several utility commands useful +in the construction of test suites for code instrumented to be +run by evaluation of Tcl commands. Notably the built-in commands +of the Tcl library itself are tested by a test suite using the +tcltest package. + + + + + .PP The Tcl test suite consists of multiple .test files, each of which contains multiple test cases. Each test case consists of a call to @@ -391,7 +376,7 @@ names. This makes the behavior of the second form different from the first form in some cases. .PP The first form for the \fBtest\fR command: -.DS +.CS test \fIname\fR \fIdescription\fR ?-constraints \fIkeywordList|expression\fR ?-setup \fIsetupScript\fR? @@ -402,10 +387,10 @@ test \fIname\fR \fIdescription\fR ?-errorOutput \fIexpectedError\fR? ?-returnCodes \fIcodeList\fR? ?-match \fImode\fR? -.DE +.CE .PP The second form for the \fBtest\fR command (adds brace grouping): -.DS +.CS test \fIname\fR \fIdescription\fR { ?-constraints \fIkeywordList|expression\fR ?-setup \fIsetupScript\fR? @@ -417,11 +402,11 @@ test \fIname\fR \fIdescription\fR { ?-returnCodes \fIcodeList\fR? ?-match \fImode\fR? } -.DE +.CE The \fIname\fR argument should follow the pattern: -.DS +.CS <target>-<majorNum>.<minorNum> -.DE +.CE For white-box (regression) tests, the target should be the name of the C function or Tcl procedure being tested. For black-box tests, the target should be the name of the feature being tested. Related tests @@ -622,9 +607,9 @@ test can only be run if the current app can be spawned via a pipe .SH "RUNNING TEST FILES" Use the following command to run a test file that uses package tcltest: -.DS +.CS <shell> <testFile> ?<option> ?<value>?? ... -.DE +.CE Command line options include (tcltest accessor procs that correspond to each flag are listed at the end of each flag description in parenthesis): @@ -794,27 +779,27 @@ match its expected return code. You can set \fBtcltest::verbose\fR either interactively (after the \fBtcltest\fR package has been loaded) or by using the command line argument \fB-verbose\fR, for example: -.DS +.CS tclsh socket.test -verbose 'body pass skip' -.DE +.CE .SH "CONTENTS OF A TEST FILE" Test files should begin by loading the \fBtcltest\fR package: -.DS +.CS package require tcltest namespace import -force tcltest::* -.DE +.CE Test files should end by cleaning up after themselves and calling \fBtcltest::cleanupTests\fR. The \fBtcltest::cleanupTests\fR procedure prints statistics about the number of tests that passed, skipped, and failed, and removes all files that were created using the \fBtcltest::makeFile\fR and \fBtcltest::makeDirectory\fR procedures. -.DS +.CS # Remove files created by these tests # Change to original working directory # Unset global arrays tcltest::cleanupTests return -.DE +.CE When naming test files, file names should end with a .test extension. The names of test files that contain regression (or glass-box) tests should correspond to the Tcl or C code file that they are testing. @@ -924,7 +909,7 @@ To add new flags to your customized test harness, redefine \fBtcltest::processCmdLineArgsAddFlagHook\fR to define additional flags to be parsed and \fBtcltest::processCmdLineArgsHook\fR to actually process them. For example: -.DS +.CS proc tcltest::processCmdLineArgsAddFlagHook {} { return [list -flag1 -flag2] } @@ -942,7 +927,7 @@ proc tcltest::processCmdLineArgsHook {flagArray} { return } -.DE +.CE You may also want to add usage information for these flags. This information would be displayed whenever the user specifies -help. To define additional usage information, define your own @@ -952,15 +937,15 @@ implemented. .PP Finally, if you want to add additional cleanup code to your harness you can define your own \fBtcltest::cleanupTestsHook\fR. For example: -.DS +.CS proc tcltest::cleanupTestsHook {} { # Add your cleanup code here } -.DE +.CE .SH EXAMPLES .IP [1] A simple test file (foo.test) -.DS +.CS package require tcltest namespace import -force ::tcltest::* @@ -968,10 +953,10 @@ test foo-1.1 {save 1 in variable name foo} -body {set foo 1} -result 1 tcltest::cleanupTests return -.DE +.CE .IP [2] A simple all.tcl -.DS +.CS package require tcltest namespace import -force ::tcltest::* @@ -979,21 +964,21 @@ tcltest::testsDirectory [file dir [info script]] tcltest::runAllTests return -.DE +.CE .IP [3] Running a single test -.DS +.CS tclsh foo.test -.DE +.CE .IP [4] Running multiple tests -.DS +.CS tclsh all.tcl -file 'foo*.test' -notfile 'foo2.test' -.DE +.CE .IP [5] A test that uses the unixOnly constraint and should only be run on Unix -.DS +.CS test getAttribute-1.1 {testing file permissions} { -constraints {unixOnly} -body { @@ -1001,10 +986,10 @@ test getAttribute-1.1 {testing file permissions} { } -result {00644} } -.DE +.CE .IP [6] A test containing an constraint expression that evaluates to true (a case where the test would be run) if it is being run on unix and if threads are not being tested -.DS +.CS test testOnUnixWithoutThreads-1.1 { this test runs only on unix and only if we're not testing threads @@ -1014,7 +999,7 @@ test testOnUnixWithoutThreads-1.1 { # some script goes here } } -.DE +.CE .SH "KNOWN ISSUES" There are two known issues related to nested test commands. @@ -1022,14 +1007,14 @@ The first issue relates to the stack level in which test scripts are executed. Tests nested within other tests may be executed at the same stack level as the outermost test. For example, in the following test code: -.DS +.CS test level-1.1 {level 1} { -body { test level-2.1 {level 2} { } } } -.DE +.CE any script executed in level-2.1 may be executed at the same stack level as the script defined for level-1.1. .PP |