tcltest.n

来自「tcl是工具命令语言」· N 代码 · 共 1,066 行 · 第 1/3 页

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California
'\" 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.38 2003/01/24 16:33:35 dgp Exp $
'\" 
.so man.macros
.TH "tcltest" n 2.2 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.2?\fR
.sp
\fBtcltest::test \fIname description ?option value ...?\fR
\fBtcltest::test \fIname description ?constraints? body result\fR
.sp
\fBtcltest::loadTestedCommands\fR
\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::cleanupTests \fI?runningMultipleTests?\fR
\fBtcltest::runAllTests\fR
.sp
.VS 2.1
\fBtcltest::configure\fR
\fBtcltest::configure \fIoption\fR
\fBtcltest::configure \fIoption value ?option value ...?\fR
\fBtcltest::customMatch \fImode command\fR
.VE
\fBtcltest::testConstraint \fIconstraint ?value?\fR
\fBtcltest::outputChannel \fI?channelID?\fR
\fBtcltest::errorChannel \fI?channelID?\fR
\fBtcltest::interpreter \fI?interp?\fR
.sp
\fBtcltest::debug \fI?level?\fR
\fBtcltest::errorFile \fI?filename?\fR
\fBtcltest::limitConstraints \fI?boolean?\fR
\fBtcltest::loadFile \fI?filename?\fR
\fBtcltest::loadScript \fI?script?\fR
\fBtcltest::match \fI?patternList?\fR
\fBtcltest::matchDirectories \fI?patternList?\fR
\fBtcltest::matchFiles \fI?patternList?\fR
\fBtcltest::outputFile \fI?filename?\fR
\fBtcltest::preserveCore \fI?level?\fR
\fBtcltest::singleProcess \fI?boolean?\fR
\fBtcltest::skip \fI?patternList?\fR
\fBtcltest::skipDirectories \fI?patternList?\fR
\fBtcltest::skipFiles \fI?patternList?\fR
\fBtcltest::temporaryDirectory \fI?directory?\fR
\fBtcltest::testsDirectory \fI?directory?\fR
\fBtcltest::verbose \fI?level?\fR
.sp
\fBtcltest::test \fIname description optionList\fR
\fBtcltest::bytestring \fIstring\fR
\fBtcltest::normalizeMsg \fImsg\fR
\fBtcltest::normalizePath \fIpathVar\fR
\fBtcltest::workingDirectory \fI?dir?\fR
.fi
.BE
.SH DESCRIPTION
.PP
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
All the commands provided by the \fBtcltest\fR package are defined
in and exported from the \fB::tcltest\fR namespace, as indicated in
the \fBSYNOPSIS\fR above.  In the following sections, all commands
will be described by their simple names, in the interest of brevity.
.PP
The central command of \fBtcltest\fR is [\fBtest\fR] that defines
and runs a test.  Testing with [\fBtest\fR] involves evaluation
of a Tcl script and comparing the result to an expected result, as
configured and controlled by a number of options.  Several other
commands provided by \fBtcltest\fR govern the configuration of
[\fBtest\fR] and the collection of many [\fBtest\fR] commands into
test suites.
.PP
See \fBCREATING TEST SUITES WITH TCLTEST\fR below for an extended example
of how to use the commands of \fBtcltest\fR to produce test suites
for your Tcl-enabled code.
.SH COMMANDS
.TP
\fBtest\fR \fIname description ?option value ...?\fR
Defines and possibly runs a test with the name \fIname\fR and
description \fIdescription\fR.  The name and description of a test
are used in messages reported by [\fBtest\fR] during the
test, as configured by the options of \fBtcltest\fR.  The
remaining \fIoption value\fR arguments to [\fBtest\fR]
define the test, including the scripts to run, the conditions
under which to run them, the expected result, and the means
by which the expected and actual results should be compared.
See \fBTESTS\fR below for a complete description of the valid
options and how they define a test.  The [\fBtest\fR] command
returns an empty string.  
.TP
\fBtest\fR \fIname description ?constraints? body result\fR
This form of [\fBtest\fR] is provided to support test suites written
for version 1 of the \fBtcltest\fR package, and also a simpler
interface for a common usage.  It is the same as
[\fBtest\fR \fIname description\fB -constraints \fIconstraints\fB -body
\fIbody\fB -result \fIresult\fR].  All other options to [\fBtest\fR]
take their default values.  When \fIconstraints\fR is omitted, this
form of [\fBtest\fR] can be distinguished from the first because
all \fIoption\fRs begin with ``-''.
.TP
\fBloadTestedCommands\fR
Evaluates in the caller's context the script specified by 
[\fBconfigure -load\fR] or [\fBconfigure -loadfile\fR].
Returns the result of that script evaluation, including any error
raised by the script.  Use this command and the related
configuration options to provide the commands to be tested to
the interpreter running the test suite.
.TP
\fBmakeFile\fR \fIcontents name ?directory?\fR
Creates a file named \fIname\fR relative to
directory \fIdirectory\fR and write \fIcontents\fR
to that file using the encoding [\fBencoding system\fR].
If \fIcontents\fR does not end with a newline, a newline
will be appended so that the file named \fIname\fR
does end with a newline.  Because the system encoding is used,
this command is only suitable for making text files.
The file will be removed by the next evaluation
of [\fBcleanupTests\fR], unless it is removed by
[\fBremoveFile\fR] first.  The default value of
\fIdirectory\fR is the directory [\fBconfigure -tmpdir\fR].
Returns the full path of the file created.  Use this command
to create any text file required by a test with contents as needed.
.TP
\fBremoveFile\fR \fIname ?directory?\fR
Forces the file referenced by \fIname\fR to be removed.  This file name
should be relative to \fIdirectory\fR.   The default value of
\fIdirectory\fR is the directory [\fBconfigure -tmpdir\fR].
Returns an empty string.  Use this command to delete files
created by [\fBmakeFile\fR].  
.TP
\fBmakeDirectory\fR \fIname ?directory?\fR
Creates a directory named \fIname\fR relative to directory \fIdirectory\fR.
The directory will be removed by the next evaluation of [\fBcleanupTests\fR],
unless it is removed by [\fBremoveDirectory\fR] first.
The default value of \fIdirectory\fR is the directory
[\fBconfigure -tmpdir\fR].
Returns the full path of the directory created.  Use this command
to create any directories that are required to exist by a test.
.TP
\fBremoveDirectory\fR \fIname ?directory?\fR
Forces the directory referenced by \fIname\fR to be removed. This
directory should be relative to \fIdirectory\fR.
The default value of \fIdirectory\fR is the directory
[\fBconfigure -tmpdir\fR].
Returns an empty string.  Use this command to delete any directories
created by [\fBmakeDirectory\fR].  
.TP
\fBviewFile\fR \fIfile ?directory?\fR
Returns the contents of \fIfile\fR, except for any
final newline, just as [\fBread -nonewline\fR] would return.
This file name should be relative to \fIdirectory\fR.   
The default value of \fIdirectory\fR is the directory
[\fBconfigure -tmpdir\fR].  Use this command
as a convenient way to turn the contents of a file generated
by a test into the result of that test for matching against
an expected result.  The contents of the file are read using
the system encoding, so its usefulness is limited to text
files.
.TP
\fBcleanupTests\fR
Intended to clean up and summarize after several tests have been
run.  Typically called once per test file, at the end of the file
after all tests have been completed.  For best effectiveness, be
sure that the [\fBcleanupTests\fR] is evaluated even if an error
occurs earlier in the test file evaluation.  
.sp
Prints statistics about the tests run and removes files that were
created by [\fBmakeDirectory\fR] and [\fBmakeFile\fR] since the
last [\fBcleanupTests\fR].  Names of files and directories 
in the directory [\fBconfigure -tmpdir\fR] created since
the last [\fBcleanupTests\fR], but not created by
[\fBmakeFile\fR] or [\fBmakeDirectory\fR] are printed
to [\fBoutputChannel\fR].  This command also restores the original
shell environment, as described by the ::env
array. Returns an empty string.
.TP
\fBrunAllTests\fR
This is a master command meant to run an entire suite of tests,
spanning multiple files and/or directories, as governed by
the configurable options of \fBtcltest\fR.  See \fBRUNNING ALL TESTS\fR
below for a complete description of the many variations possible
with [\fBrunAllTests\fR].
.SH "CONFIGURATION COMMANDS"
.VS
.TP
\fBconfigure\fR
Returns the list of configurable options supported by \fBtcltest\fR.
See \fBCONFIGURABLE OPTIONS\fR below for the full list of options,
their valid values, and their effect on \fBtcltest\fR operations.
.TP
\fBconfigure \fIoption\fR
Returns the current value of the supported configurable option \fIoption\fR.
Raises an error if \fIoption\fR is not a supported configurable option.
.TP
\fBconfigure \fIoption value ?option value ...?\fR
Sets the value of each configurable option \fIoption\fR to the
corresponding value \fIvalue\fR, in order.  Raises an error if
an \fIoption\fR is not a supported configurable option, or if
\fIvalue\fR is not a valid value for the corresponding \fIoption\fR,
or if a \fIvalue\fR is not provided.  When an error is raised, the
operation of [\fBconfigure\fR] is halted, and subsequent \fIoption value\fR
arguments are not processed.
.sp
If the environment variable \fB::env(TCLTEST_OPTIONS)\fR exists when
the \fBtcltest\fR package is loaded (by [\fBpackage require tcltest\fR])
then its value is taken as a list of arguments to pass to [\fBconfigure\fR].
This allows the default values of the configuration options to be
set by the environment.
.TP
\fBcustomMatch \fImode script\fR
Registers \fImode\fR as a new legal value of the \fB-match\fR option
to [\fBtest\fR].  When the \fB-match \fImode\fR option is
passed to [\fBtest\fR], the script \fIscript\fR will be evaluated
to compare the actual result of evaluating the body of the test
to the expected result.
To perform the match, the \fIscript\fR is completed with two additional
words, the expected result, and the actual result, and the completed script
is evaluated in the global namespace.
The completed script is expected to return a boolean value indicating
whether or not the results match.  The built-in matching modes of
[\fBtest\fR] are \fBexact\fR, \fBglob\fR, and \fBregexp\fR.
.VE
.TP
\fBtestConstraint \fIconstraint ?boolean?\fR
Sets or returns the boolean value associated with the named \fIconstraint\fR.
See \fBTEST CONSTRAINTS\fR below for more information.
.TP
\fBinterpreter\fR \fI?executableName?\fR
Sets or returns the name of the executable to be [\fBexec\fR]ed by
[\fBrunAllTests\fR] to run each test file when
[\fBconfigure -singleproc\fR] is false.
The default value for [\fBinterpreter\fR] is the name of the
currently running program as returned by [\fBinfo nameofexecutable\fR].
.TP
\fBoutputChannel\fR \fI?channelID?\fR
Sets or returns the output channel ID.  This defaults to stdout.
Any test that prints test related output should send
that output to [\fBoutputChannel\fR] rather than letting
that output default to stdout.
.TP
\fBerrorChannel\fR \fI?channelID?\fR
Sets or returns the error channel ID.  This defaults to stderr.
Any test that prints error messages should send
that output to [\fBerrorChannel\fR] rather than printing
directly to stderr.
.SH "SHORTCUT COMMANDS"
.TP
\fBdebug \fI?level?\fR
Same as [\fBconfigure -debug \fI?level?\fR].
.TP
\fBerrorFile \fI?filename?\fR
Same as [\fBconfigure -errfile \fI?filename?\fR].
.TP
\fBlimitConstraints \fI?boolean?\fR
Same as [\fBconfigure -limitconstraints \fI?boolean?\fR].
.TP
\fBloadFile \fI?filename?\fR
Same as [\fBconfigure -loadfile \fI?filename?\fR].
.TP
\fBloadScript \fI?script?\fR
Same as [\fBconfigure -load \fI?script?\fR].
.TP
\fBmatch \fI?patternList?\fR
Same as [\fBconfigure -match \fI?patternList?\fR].
.TP
\fBmatchDirectories \fI?patternList?\fR
Same as [\fBconfigure -relateddir \fI?patternList?\fR].
.TP
\fBmatchFiles \fI?patternList?\fR
Same as [\fBconfigure -file \fI?patternList?\fR].
.TP
\fBoutputFile \fI?filename?\fR
Same as [\fBconfigure -outfile \fI?filename?\fR].
.TP
\fBpreserveCore \fI?level?\fR
Same as [\fBconfigure -preservecore \fI?level?\fR].
.TP
\fBsingleProcess \fI?boolean?\fR
Same as [\fBconfigure -singleproc \fI?boolean?\fR].
.TP
\fBskip \fI?patternList?\fR
Same as [\fBconfigure -skip \fI?patternList?\fR].
.TP
\fBskipDirectories \fI?patternList?\fR
Same as [\fBconfigure -asidefromdir \fI?patternList?\fR].
.TP
\fBskipFiles \fI?patternList?\fR
Same as [\fBconfigure -notfile \fI?patternList?\fR].
.TP
\fBtemporaryDirectory \fI?directory?\fR
Same as [\fBconfigure -tmpdir \fI?directory?\fR].
.TP
\fBtestsDirectory \fI?directory?\fR
Same as [\fBconfigure -testdir \fI?directory?\fR].
.TP
\fBverbose \fI?level?\fR
Same as [\fBconfigure -verbose \fI?level?\fR].
.SH "OTHER COMMANDS"
.PP
The remaining commands provided by \fBtcltest\fR have better
alternatives provided by \fBtcltest\fR or \fBTcl\fR itself.  They
are retained to support existing test suites, but should be avoided
in new code.
.TP
\fBtest\fR \fIname description optionList\fR
This form of [\fBtest\fR] was provided to enable passing many
options spanning several lines to [\fBtest\fR] as a single
argument quoted by braces, rather than needing to backslash quote
the newlines between arguments to [\fBtest\fR].  The \fIoptionList\fR
argument is expected to be a list with an even number of elements
representing \fIoption\fR and \fIvalue\fR arguments to pass
to [\fBtest\fR].  However, these values are not passed directly, as
in the alternate forms of [\fBswitch\fR].  Instead, this form makes
an unfortunate attempt to overthrow Tcl's substitution rules by
performing substitutions on some of the list elements as an attempt to
implement a ``do what I mean'' interpretation of a brace-enclosed
``block''.  The result is nearly impossible to document clearly, and
for that reason this form is not recommended.  See the examples in
\fBCREATING TEST SUITES WITH TCLTEST\fR below to see that this
form is really not necessary to avoid backslash-quoted newlines.
If you insist on using this form, examine
the source code of \fBtcltest\fR if you want to know the substitution
details, or just enclose the third through last argument
to [\fBtest\fR] in braces and hope for the best.
.TP
\fBworkingDirectory\fR \fI?directoryName?\fR
Sets or returns the current working directory when the test suite is
running.  The default value for workingDirectory is the directory in
which the test suite was launched.  The Tcl commands [\fBcd\fR] and
[\fBpwd\fR] are sufficient replacements.
.TP
\fBnormalizeMsg\fR \fImsg\fR
Returns the result of removing the ``extra'' newlines from \fImsg\fR,
where ``extra'' is rather imprecise.  Tcl offers plenty of string
processing commands to modify strings as you wish, and
[\fBcustomMatch\fR] allows flexible matching of actual and expected
results.