summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rwxr-xr-xdoc/tcltest2.n124
1 files changed, 67 insertions, 57 deletions
diff --git a/doc/tcltest2.n b/doc/tcltest2.n
index f012195..90c621f 100755
--- a/doc/tcltest2.n
+++ b/doc/tcltest2.n
@@ -7,7 +7,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: tcltest2.n,v 1.2 2000/09/29 22:47:33 jenn Exp $
+'\" RCS: @(#) $Id: tcltest2.n,v 1.3 2000/10/19 18:00:55 jenn Exp $
'\"
.so man.macros
.TH "tcltest" n 8.4 Tcl "Tcl Built-In Commands"
@@ -19,6 +19,7 @@ tcltest \- Test harness support code and utilities
\fBpackage require tcltest ?2.0?\fP
.sp
\fBtcltest::test \fIname desc ?option value? ?option value? ...\fR
+.br
\fBtcltest::test \fIname desc {?option value? ?option value? ...}\fR
.sp
\fBtcltest::cleanupTests \fI?runningMultipleTests?\fR
@@ -31,7 +32,7 @@ tcltest \- Test harness support code and utilities
.sp
\fBtcltest::debug \fI?level?\fR
.sp
-\fBtcltest::verbose \fI?level?\fR
+\fBtcltest::verbose \fI?levelList?\fR
.sp
\fBtcltest::preserveCore \fI?level?\fR
.sp
@@ -71,15 +72,15 @@ tcltest \- Test harness support code and utilities
.sp
\fBtcltest::errorFile \fI?filename?\fR
.sp
-\fBtcltest::makeFile \fIcontents name\fR
+\fBtcltest::makeFile \fIcontents name ?directory?\fR
.sp
-\fBtcltest::removeFile \fIname\fR
+\fBtcltest::removeFile \fIname ?directory?\fR
.sp
-\fBtcltest::makeDirectory \fIname\fR
+\fBtcltest::makeDirectory \fIname ?directory?\fR
.sp
-\fBtcltest::removeDirectory \fIname\fR
+\fBtcltest::removeDirectory \fIname ?directory?\fR
.sp
-\fBtcltest::viewFile \fIname\fR
+\fBtcltest::viewFile \fIname ?directory?\fR
.sp
\fBtcltest::normalizeMsg \fImsg\fR
.sp
@@ -179,20 +180,22 @@ Display information regarding what individual procs in the test
harness are doing.
.RE
.TP
-\fBtcltest::verbose\fR \fI?level?\fR
-Sets or returns the current verbosity level. This level must be a
-substring of "bpst". The default verbosity level is "b". See the
-"Test output" section for a more detailed explanation of this
-option. Levels are defined as:
+\fBtcltest::verbose\fR \fI?levelList?\fR
+Sets or returns the current verbosity level. The default verbosity
+level is "body". See the "Test output" section for a more detailed
+explanation of this option. Levels are defined as:
.RS
-.IP b
+.IP body
Display the body of failed tests
-.IP p
+.IP pass
Print output when a test passes
-.IP s
+.IP skip
Print output when a test is skipped
-.IP t
+.IP start
Print output whenever a test starts
+.IP error
+Print errorInfo and errorCode, if they exist, when a test return code
+does not match its expected return code
.RE
.TP
\fBtcltest::preserveCore\fR \fI?level?\fR
@@ -318,24 +321,20 @@ that output to \fItcltest::errorChannel\fR or
\fItcltest::outputChannel\fR rather than letting
that output default to stdout.
.TP
-\fBtcltest::mainThread\fR
-Sets or returns the main thread ID. This defaults to 1. This is the
-only thread that is not killed by tcltest::threadReap and is set
-according to the return value of \fItestthread names\fR at
-initialization.
-.TP
-\fBtcltest::makeFile\fP \fIcontents name\fR
+\fBtcltest::makeFile\fP \fIcontents name ?directory?\fR
Create a file that will be automatically be removed by
\fBtcltest::cleanupTests\fR at the end of a test file. This file is
-created relative to tcltest::temporaryDirectory.
+created relative to \fIdirectory\fR. If left unspecified,
+\fIdirectory\fR defaults to tcltest::temporaryDirectory.
Returns the full path of the file created.
.TP
-\fBtcltest::removeFile\fP \fIname\fR
+\fBtcltest::removeFile\fP \fIname ?directory?\fR
Force the file referenced by \fIname\fR to be removed. This file name
-should be relative to \fItcltest::temporaryDirectory\fR. This proc has no
-defined return values.
+should be relative to \fIdirectory\fR. If left unspecified,
+\fIdirectory\fR defaults to tcltest::temporaryDirectory. This proc
+has no defined return values.
.TP
-\fBtcltest::makeDirectory\fP \fIname\fR
+\fBtcltest::makeDirectory\fP \fIname ?directory?\fR
Create a directory named \fIname\fR that will automatically be removed
by \fBtcltest::cleanupTests\fR at the end of a test file. This
directory is created relative to tcltest::temporaryDirectory.
@@ -343,11 +342,14 @@ Returns the full path of the directory created.
.TP
\fBtcltest::removeDirectory\fP \fIname\fR
Force the directory referenced by \fIname\fR to be removed. This
-directory should be relative to tcltest::temporaryDirectory. This proc
+directory should be relative to \fIdirectory\fR. If left unspecified,
+\fIdirectory\fR defaults to tcltest::temporaryDirectory. This proc
has no defined return value.
.TP
-\fBtcltest::viewFile\fP \fIfile\fR
-Returns the contents of \fIfile\fR.
+\fBtcltest::viewFile\fP \fIfile ?directory?\fR
+Returns the contents of \fIfile\fR. This file name
+should be relative to \fIdirectory\fR. If left unspecified,
+\fIdirectory\fR defaults to tcltest::temporaryDirectory.
.TP
\fBtcltest::normalizeMsg\fP \fImsg\fR
Remove extra newlines from \fImsg\fR.
@@ -385,6 +387,12 @@ main thread. It gets the ID of the main thread by calling
\fItestthread names\fR during initialization. This value is stored in
\fItcltest::mainThread\fR. \fBtcltest::threadReap\fR returns the
number of existing threads at completion.
+.TP
+\fBtcltest::mainThread\fR
+Sets or returns the main thread ID. This defaults to 1. This is the
+only thread that is not killed by tcltest::threadReap and is set
+according to the return value of \fItestthread names\fR at
+initialization.
.SH TESTS
The \fBtest\fR procedure runs a test script and prints an error
message if the script's result does not match the expected result.
@@ -530,7 +538,7 @@ test can only be run if all test files are sourced into a single interpreter
\fIunix\fR
test can only be run on any UNIX platform
.TP
-\fIpc\fR
+\fIwin\fR
test can only be run on any Windows platform
.TP
\fInt\fR
@@ -545,16 +553,16 @@ test can only be run on any Windows 98 platform
\fImac\fR
test can only be run on any Mac platform
.TP
-\fIunixOrPc\fR
-test can only be run on a UNIX or PC platform
+\fIunixOrWin\fR
+test can only be run on a UNIX or Windows platform
.TP
-\fImacOrPc\fR
-test can only be run on a Mac or PC platform
+\fImacOrWin\fR
+test can only be run on a Mac or Windows platform
.TP
\fImacOrUnix\fR
test can only be run on a Mac or UNIX platform
.TP
-\fItempNotPc\fR
+\fItempNotWin\fR
test can not be run on Windows. This flag is used to temporarily
disable a test.
.TP
@@ -566,7 +574,7 @@ to temporarily disable a test.
test crashes if it's run on UNIX. This flag is used to temporarily
disable a test.
.TP
-\fIpcCrash\fR
+\fIwinCrash\fR
test crashes if it's run on Windows. This flag is used to temporarily
disable a test.
.TP
@@ -609,8 +617,8 @@ test can only be run if platform supports async flush and async close
on a pipe
.TP
\fIunixExecs\fR
-test can only be run if this machine has commands such as 'cat', 'echo',
-etc. available.
+test can only be run if this machine has Unix-style commands 'cat', 'echo',
+'sh', 'wc', 'rm', 'sleep', 'fgrep', 'ps', 'chmod', and 'mkdir' available
.TP
\fIhasIsoLocale\fR
test can only be run if can switch to an ISO locale
@@ -645,9 +653,10 @@ display usage information.
if <bool> is 0, run test files in separate interpreters. if 1, source test
files into the current intpreter. (tcltest::singleProcess)
.TP
-\fB-verbose <level>\fR
-set the level of verbosity to a substring of "bpst". See the "Test
-output" section for an explanation of this option. (tcltest::verbose)
+\fB-verbose <levelList>\fR
+set the level of verbosity to a list containing 0 or more of "body",
+"pass", "skip", "start", and "error". See the "Test output" section
+for an explanation of this option. (tcltest::verbose)
.TP
\fB-match <matchList>\fR
only run tests that match one or more of the glob patterns in
@@ -748,9 +757,9 @@ defaults to stderr. (tcltest::errorFile)
.PP
You can specify any of the above options on the command line or by
defining an environment variable named TCLTEST_OPTIONS containing a
-list of options (e.g. "-debug 3 -verbose 'ps'"). This environment
-variable is evaluated before the command line arguments. Options
-specified on the command line override those specified in
+list of options (e.g. "-debug 3 -verbose 'pass skip'"). This
+environment variable is evaluated before the command line arguments.
+Options specified on the command line override those specified in
TCLTEST_OPTIONS.
.PP
A second way to run tets is to start up a shell, load the
@@ -783,25 +792,26 @@ passed, skipped, and failed is printed to
statistical information, output can be controlled on a per-test basis
by the \fBtcltest::verbose\fR variable.
.PP
-\fBtcltest::verbose\fR can be set to any substring or permutation
-of "bpst". In the string "bpst", the 'b' stands for a test's "body",
-the 'p' stands for "passed" tests, the 's' stands for "skipped"
-tests, and the 't' indicates when a test "starts".
-The default value of \fBtcltest::verbose\fR is "b". If 'b'
-is present, then the entire body of the test is printed for each
-failed test, otherwise only the test's name, desired output, and
-actual output, are printed for each failed test. If 'p' is present,
+\fBtcltest::verbose\fR can be set to any combination of "body",
+"skip", "pass", "start", or "error". The default value of
+\fBtcltest::verbose\fR is "body". If "body" is present, then the
+entire body of the test is printed for each failed test, otherwise
+only the test's name, desired output, and
+actual output, are printed for each failed test. If "pass" is present,
then a line is printed for each passed test, otherwise no line is
-printed for passed tests. If 's' is present, then a line (containing
+printed for passed tests. If "skip" is present, then a line (containing
the consraints that cause the test to be skipped) is printed for each
-skipped test, otherwise no line is printed for skipped tests. If 't'
+skipped test, otherwise no line is printed for skipped tests. If "start"
is present, then a line is printed each time a new test starts.
+If "error" is present, then the content of errorInfo and errorCode (if
+they are defined) is printed for each test whose return code doesn't
+match its expected return code.
.PP
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
-tclsh socket.test -verbose bps
+tclsh socket.test -verbose 'body pass skip'
.DE
.SH "CONTENTS OF A TEST FILE"
Test files should begin by loading the \fBtcltest\fR package: