summaryrefslogtreecommitdiffstats
path: root/doc/tcltest.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/tcltest.n')
-rw-r--r--doc/tcltest.n93
1 files changed, 47 insertions, 46 deletions
diff --git a/doc/tcltest.n b/doc/tcltest.n
index b9dc2c7..dec126e 100644
--- a/doc/tcltest.n
+++ b/doc/tcltest.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: tcltest.n,v 1.10 2000/10/24 22:30:25 jenn Exp $
+'\" RCS: @(#) $Id: tcltest.n,v 1.11 2001/03/30 00:56:16 hobbs Exp $
'\"
.so man.macros
.TH "tcltest" n 8.4 Tcl "Tcl Built-In Commands"
@@ -16,7 +16,7 @@
.SH NAME
tcltest \- Test harness support code and utilities
.SH SYNOPSIS
-\fBpackage require tcltest ?2.0?\fP
+\fBpackage require tcltest ?2.0?\fR
.sp
\fBtcltest::test \fIname desc ?option value? ?option value? ...\fR
.br
@@ -112,9 +112,9 @@ customized test harness implementation. For more defails, see the
section \fI"How to Customize the Test Harness"\fR.
.SH COMMANDS
.TP
-\fBtcltest::test\fP \fIname desc ?option value? ?option value? ...\fR
+\fBtcltest::test\fR \fIname desc ?option value? ?option value? ...\fR
.TP
-\fBtcltest::test\fP \fIname desc {?option value? ?option value? ...}\fR
+\fBtcltest::test\fR \fIname desc {?option value? ?option value? ...}\fR
The \fBtcltest::test\fR command runs the value supplied for attribute
\fIscript\fR and compares its result to possible results.
It prints an error message if actual results and expected results do
@@ -123,7 +123,7 @@ successfully. Any other return value indicates that an error has
occurred in the tcltest package. See the \fI"Tests"\fR section for
more details on this command.
.TP
-\fBtcltest::cleanupTests\fP \fI?runningMultipleTests?\fR
+\fBtcltest::cleanupTests\fR \fI?runningMultipleTests?\fR
This command should be called at the end of a test file. It prints
statistics about the tests run and removes files that were created by
\fBtcltest::makeDirectory\fR and \fBtcltest::makeFile\fR. Names
@@ -137,7 +137,7 @@ file. Tcl files files are generally used to run multiple tests. For
more details on how to run multiple tests, please see the section
\fI"Running test files"\fR. This proc has no defined return value.
.TP
-\fBtcltest::runAllTests\fP
+\fBtcltest::runAllTests\fR
This command should be used in your 'all.tcl' file. It is used to
loop over test files and directories, determining which test files to
run and then running them. Note that this test calls
@@ -277,7 +277,7 @@ Sets or returns the glob pattern list that determines which test
subdirectories (of those matched by tcltest::matchDirectories) should
be skipped. The default value for \fIglobPatternList\fR is {}.
.TP
-\fBtcltest::loadTestedCommands\fP
+\fBtcltest::loadTestedCommands\fR
This command uses the script specified via the \fI-load\fR or
\fI-loadfile\fR options or the tcltest::loadScript or
tcltest::loadFile procs to load the commands checked by the test suite.
@@ -321,45 +321,45 @@ that output to \fItcltest::errorChannel\fR or
\fItcltest::outputChannel\fR rather than letting
that output default to stdout.
.TP
-\fBtcltest::makeFile\fP \fIcontents name ?directory?\fR
+\fBtcltest::makeFile\fR \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 \fIdirectory\fR. If left unspecified,
\fIdirectory\fR defaults to tcltest::temporaryDirectory.
Returns the full path of the file created.
.TP
-\fBtcltest::removeFile\fP \fIname ?directory?\fR
+\fBtcltest::removeFile\fR \fIname ?directory?\fR
Force the file referenced by \fIname\fR to be removed. This file name
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 ?directory?\fR
+\fBtcltest::makeDirectory\fR \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.
Returns the full path of the directory created.
.TP
-\fBtcltest::removeDirectory\fP \fIname\fR
+\fBtcltest::removeDirectory\fR \fIname\fR
Force the directory referenced by \fIname\fR to be removed. This
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 ?directory?\fR
+\fBtcltest::viewFile\fR \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
+\fBtcltest::normalizeMsg\fR \fImsg\fR
Remove extra newlines from \fImsg\fR.
.TP
-\fBtcltest::normalizePath\fP \fIpathVar\fR
+\fBtcltest::normalizePath\fR \fIpathVar\fR
Resolves symlinks in a path, thus creating a path without internal
redirection. It is assumed that \fIpathVar\fR is absolute.
\fIpathVar\fR is modified in place.
.TP
-\fBtcltest::bytestring\fP \fIstring\fR
+\fBtcltest::bytestring\fR \fIstring\fR
Construct a string that consists of the requested sequence of bytes,
as opposed to a string of properly formed UTF-8 characters using the
value supplied in \fIstring\fR. This allows the tester to create
@@ -367,19 +367,19 @@ denormalized or improperly formed strings to pass to C procedures that
are supposed to accept strings with embedded NULL types and confirm
that a string result has a certain pattern of bytes.
.TP
-\fBtcltest::saveState\fP
+\fBtcltest::saveState\fR
Save procedure and global variable names.
A test file might contain calls to \fBtcltest::saveState\fR and
\fB::tcltest:restoreState\fR if it creates or deletes global variables
or procs.
.TP
-\fBtcltest::restoreState\fP
+\fBtcltest::restoreState\fR
Restore procedure and global variable names.
A test file might contain calls to \fBtcltest::saveState\fR and
\fB::tcltest:restoreState\fR if it creates or deletes global variables
or procs.
.TP
-\fBtcltest::threadReap\fP
+\fBtcltest::threadReap\fR
\fBtcltest::threadReap\fR only works if \fItestthread\fR is
defined, generally by compiling tcltest. If \fItestthread\fR is
defined, \fBtcltest::threadReap\fR kills all threads except for the
@@ -410,30 +410,30 @@ first form in some cases.
.PP
The first form for the \fBtest\fR command:
.DS
-test \fIname\fR \fIdescription\fR
+test \fIname\fR \fIdescription\fR
?-constraints \fIkeywordList|expression\fR
?-setup \fIsetupScript\fR?
?-body \fItestScript\fR?
?-cleanup \fIcleanupScript\fR?
?-result \fIexpectedAnswer\fR?
- ?-output \fIexpectedOutput\fR?
- ?-errorOutput \fIexpectedError\fR?
+ ?-output \fIexpectedOutput\fR?
+ ?-errorOutput \fIexpectedError\fR?
?-returnCodes \fIcodeList\fR?
?-match \fIexact|glob|regexp\fR?
.DE
.PP
-The second form for the \fBtest\fR command:
+The second form for the \fBtest\fR command (adds brace grouping):
.DS
test \fIname\fR \fIdescription\fR {
?-constraints \fIkeywordList|expression\fR
?-setup \fIsetupScript\fR?
?-body \fItestScript\fR?
?-cleanup \fIcleanupScript\fR?
- ?-result \fIexpectedAnswer\fR?
- ?-output\fIexpectedOutput\fR?
- ?-errorOutput \fIexpectedError\fR?
+ ?-result \fIexpectedAnswer\fR?
+ ?-output\fIexpectedOutput\fR?
+ ?-errorOutput \fIexpectedError\fR?
?-returnCodes \fIcodeList\fR?
- ?-match \fIexact|glob|regexp?
+ ?-match \fIexact|glob|regexp\fR?
}
.DE
The \fIname\fR argument should follow the pattern:
@@ -454,7 +454,7 @@ in the description.
.PP
Valid attributes and associated values are:
.TP
-\fB-constraints \fIkeywordList|expression\fR\fP
+\fB-constraints \fIkeywordList|expression\fR
The optional \fIconstraints\fR attribute can be list of one or more
keywords or an expression. If the \fIconstraints\fR value consists of
keywords, each of these keywords being the name of a constraint
@@ -467,49 +467,49 @@ constraints should be added to any tests that should
not always be run. See the "Test Constraints" section for a list of built-in
constraints and information on how to add your own constraints.
.TP
-\fB-setup \fIscript\fR\fP
+\fB-setup \fIscript\fR
The optional \fIsetup\fR attribute indicates a script that will be run
before the script indicated by the \fIscript\fR attribute. If setup
fails, the test will fail.
.TP
-\fB-body \fIscript\fR\fP
+\fB-body \fIscript\fR
The \fIbody\fR attribute indicates the script to run to carry out the
test. It must return a result that can be checked for correctness.
If left unspecified, the script value will be {}.
.TP
-\fB-cleanup \fIscript\fR\fP
+\fB-cleanup \fIscript\fR
The optional \fIcleanup\fR attribute indicates a script that will be
run after the script indicated by the \fIscript\fR attribute. If
cleanup fails, the test will fail.
.TP
-\fB-match \fIregexp|glob|exact\fP
+\fB-match \fIregexp|glob|exact\fR
The \fImatch\fR attribute determines how expected answers supplied in
-\fIresult\fR, \fIoutput\fR, and \fRerrorOutput\fR are compared. Valid
-options for the value supplied are "regexp", "glob", and
-"exact". If \fImatch\fR is not specified, the comparisons will be
-done in "exact" mode by default.
+\fIresult\fR, \fIoutput\fR, and \fIerrorOutput\fR are compared. Valid
+options for the value supplied are ``regexp'', ``glob'', and
+``exact''. If \fImatch\fR is not specified, the comparisons will be
+done in ``exact'' mode by default.
.TP
-\fB-result \fIexpectedValue\fR\fP
+\fB-result \fIexpectedValue\fR
The \fIresult\fR attribute supplies the comparison value with which
the return value from script will be compared.
If left unspecified, the default
\fIexpectedValue\fR will be the empty list.
.TP
-\fB-output \fIexpectedValue\fR\fP
+\fB-output \fIexpectedValue\fR
The \fIoutput\fR attribute supplies the comparison value with which
any output sent to stdout or tcltest::outputChannel during the script
run will be compared. Note that only output printed using
puts is used for comparison. If \fIoutput\fR is not specified, output
sent to stdout and tcltest::outputChannel is not processed for comparison.
.TP
-\fB-errorOutut \fIexpectedValue\fR\fP
+\fB-errorOutut \fIexpectedValue\fR
The \fIerrorOutput\fR attribute supplies the comparison value with which
any output sent to stderr or tcltest::errorChannel during the script
run will be compared. Note that only output printed using
puts is used for comparison. If \fIerrorOutut\fR is not specified, output
sent to stderr and tcltest::errorChannel is not processed for comparison.
.TP
-\fB-returnCodes \fIexpectedCodeList\fR\fP
+\fB-returnCodes \fIexpectedCodeList\fR
The optional \fIreturnCodes\fR attribute indicates which return codes
from the script supplied with the \fIscript\fR attribute are correct.
Default values for \fIexpectedCodeList\fR are 0 (normal return) and 2
@@ -524,7 +524,7 @@ the test must match expected output and error values. If all of these
conditions are not met, then the test fails.
.SH "TEST CONSTRAINTS"
Constraints are used to determine whether or not a test should be skipped.
-If a test is constrained by "unixOnly", then it will only be run if
+If a test is constrained by ``unixOnly'', then it will only be run if
the value of the constraint is true. Several
constraints are defined in the \fBtcltest\fR package. To add
constraints, you can call \fBtcltest::testConstraint\fR
@@ -922,21 +922,21 @@ To create your own custom test harness, create a .tcl file that contains your
namespace. Within this file, require package \fBtcltest\fR. Commands
that can be redefined to customize the test harness include:
.TP
-\fBtcltest::PrintUsageInfoHook\fP
+\fBtcltest::PrintUsageInfoHook\fR
print additional usage information specific to your situation.
.TP
-\fBtcltest::processCmdLineArgsFlagHook\fP
+\fBtcltest::processCmdLineArgsFlagHook\fR
tell the test harness about additional flags that you want it to understand.
.TP
-\fBtcltest::processCmdLineArgsHook\fR \fIflags\fP
+\fBtcltest::processCmdLineArgsHook\fR \fIflags\fR
process the additional flags that you told the harness about in
tcltest::processCmdLineArgsFlagHook.
.TP
-\fBtcltest::initConstraintsHook\fP
+\fBtcltest::initConstraintsHook\fR
used to add additional built-in constraints to those already defined
by \fBtcltest\fR.
.TP
-\fBtcltest::cleanupTestsHook\fP
+\fBtcltest::cleanupTestsHook\fR
do additional cleanup
.PP
.PP
@@ -1048,6 +1048,7 @@ test testOnUnixWithoutThreads-1.1 {
}
}
.DE
+
.SH "KNOWN ISSUES"
There are two known issues related to nested test commands.
The first issue relates to the stack level in which test scripts are
@@ -1083,6 +1084,6 @@ directly from C applications will not be caught by the test command.
Therefore, usage of expect_out and expect_err in the test command is
useful only for pure Tcl applications that use the puts command for
output.
+
.SH KEYWORDS
test, test harness, test suite
-