diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/tcltest.n | 598 |
1 files changed, 190 insertions, 408 deletions
diff --git a/doc/tcltest.n b/doc/tcltest.n index bffa05b..4982d7c 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -8,7 +8,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.24 2002/07/01 22:33:20 dgp Exp $ +'\" RCS: @(#) $Id: tcltest.n,v 1.25 2002/07/02 13:28:51 dgp Exp $ '\" .so man.macros .TH "tcltest" n 2.1 tcltest "Tcl Bundled Packages" @@ -510,16 +510,19 @@ easily capture output with the [\fBconfigure -outfile\fR] and [\fBconfigure -errfile\fR] options, and so that the \fB-output\fR and \fB-errorOutput\fR attributes work properly. .SH "TEST CONSTRAINTS" +.PP Constraints are used to determine whether or not a test should be skipped. Each constraint has a name, which may be any string, and a boolean value. Each [\fBtest\fR] has a \fB-constraints\fR value which is a -list of constraint names. The test will run only if all constraints -in the list are true-valued. Thus, the \fB-constraints\fR option -of [\fBtest\fR] is a convenient, symbolic way to define any conditions -required for the test to be possible or meaningful. For example, -a [\fBtest\fR] with \fB-constraints unix\fR will only be run -if the constraint \fBunix\fR is true, which indicates the test suite -is being run on a Unix platform. +list of constraint names. There are two modes of constraint control. +Most frequently, the default mode is used, indicated by a setting +of [\fBconfigure -limitconstraints\fR] to false. The test will run +only if all constraints in the list are true-valued. Thus, +the \fB-constraints\fR option of [\fBtest\fR] is a convenient, symbolic +way to define any conditions required for the test to be possible or +meaningful. For example, a [\fBtest\fR] with \fB-constraints unix\fR +will only be run if the constraint \fBunix\fR is true, which indicates +the test suite is being run on a Unix platform. .PP Each [\fBtest\fR] should include whatever \fB-constraints\fR are required to constrain it to run only where appropriate. Several @@ -639,35 +642,102 @@ to the "e" format of floating-point numbers. \fIstdio\fR test can only be run if the current app can be spawned via a pipe .PP - -Add description of -constraints and -limitconstraints here. - +The alternative constraint mode is enabled by setting the +value of [\fBconfigure -limitconstraints\fR] to true. When +that configuration is set, all existing constraints other than +those in the constraint list returned by [\fBconfigure -constraints\fR] +are set to false. When the value of [\fBconfigure -constraints\fR] +is set, all those constraints are set to true. The effect is that +when both configuration options \fB-constraints\fR and +\fB-limitconstraints\fR are in use, only those tests including +only constraints from the [\fBconfigure -constraints\fR] list +are run; all others are skipped. For example, one might set +up a configuration with +.CS +configure -constraints knownBug -limitconstraints true -verbose pass +.CE +to run exactly those tests that exercise known bugs, and discover +whether any of them pass, indicating the bug had been fixed. .SH "RUNNING ALL TESTS" - +.PP +The single command [\fBrunAllTests\fR] is evaluated to run an entire +test suite, spanning many files and directories. The configuration +options of \fBtcltest\fR control the precise operations. The +[\fBrunAllTests\fR] command begins by printing a summary of its +configuration to [\fBoutputChannel\fR]. +.PP +Test files to be evaluated are sought in the directory +[\fBconfigure -testdir\fR]. The list of files in that directory +that match any of the patterns in [\fBconfigure -file\fR] and +match none of the patterns in [\fBconfigure -notfile] is generated +and sorted. Then each file will be evaluated in turn. If +[\fBconfigure -singleproc\fR] is true, then each file will +be [\fBsource\fR]d in the caller's context. If if is false, +then a copy of [\fBinterpreter\fR] will be [\fBexec\fR]d to +evaluate each file. The multi-process operation is useful +when testing can cause errors so severe that a process +terminates. Although such an error may terminate a child +process evaluating one file, the master process can continue +with the rest of the test suite. In multi-process operation, +the configuration of \fBtcltest\fR in the master process is +passed to the child processes as command line arguments, +with the exception of [\fBconfigure -outfile\fR]. The +master process collects all output from the child process +and collates their results into one master report. Any +reports of individual test failures, or messages requested +by a [\fBconfigure -verbose\fR] setting are passed directly +on to [\fBoutputChannel\fR] by the master process. +.PP +After evaluating all selected test files, a summary of the +results is printed to [\fBoutputChannel\fR]. The summary +includes the total number of [\fBtest\fR]s evaluated, broken +down into those skipped, those passed, and those failed. +Is also notes the number of files evaluated, and the names +of any files with failing tests, or errors. A list of +the constraints that caused tests to be skipped, and the +number of tests skipped for each is also printed. Also, +messages are printed if it appears that evaluation of +a test file has caused any temporary files to be left +behind in [\fBconfigure -tmpdir\fR]. +.PP +Having completed and summarized all selected test files, +[\fBrunAllTests\fR] then recursively acts on subdirectories +of [\fBconfigure -testdir\fR]. All subdirectories that +match any of the patterns in [\fBconfigure -relateddir\fR] +and do not match any of the patterns in +[\fBconfigure -asidefromdir\fR] are examined. If +a file named \fBall.tcl\fR is found in such a directory, +it will be [\fBsource\fR]d in the caller's context. +Whether or not an examined directory contains an +\fBall.tcl\fR file, its subdirectories are also scanned +against the [\fBconfigure -relateddir\fR] and +[\fBconfigure -asidefromdir\fR] patterns. In this way, +many directories in a directory tree can have all their +test files evaluated by a single [\fBrunAllTests\fR] +command. .SH "CONFIGURABLE OPTIONS" - -.TP -\fBsingleProcess\fR \fI?value?\fR -Sets or returns a boolean indicating whether test files should be sourced -into the current interpreter by runAllTests or run in their own -processes. If \fIvalue\fR is true (1), tests are sourced into the -current interpreter. If \fIvalue\fR is false (0), tests are run in -the interpreter specified in tcltest::interpreter. The default value -for tcltest::singleProcess is false. - -.TP -\fBdebug\fR \fI?level?\fR -Sets or returns the current debug level. The debug level determines -how much tcltest package debugging information is printed to stdout. -The default debug level is 0. Levels are defined as: +The [\fBconfigure\fR] command is used to set and query the configurable +options of \fBtcltest\fR. The valid options are: +.TP +\fB-singleproc \fIboolean\fR +Controls whether or not [\fBrunAllTests\fR] spawns a child process for +each test file. No spawning when \fIboolean\fR is true. Default +value is false. +.TP +\fB-debug \fIlevel\fR +Sets the debug level to \fIlevel\fR, an integer value indicating how +much debugging information should be printed to stdout. Note that +debug messages always go to stdout, independent of the value of +[\fBconfigure -outfile\fR]. Default value is 0. Levels are defined as: .RS .IP 0 Do not display any debug information. .IP 1 Display information regarding whether a test is skipped because it -doesn't match any of the tests that were specified using -match or -tcltest::match (userSpecifiedNonMatch) or matches any of the tests -specified by -skip or tcltest::skip (userSpecifiedSkip). +doesn't match any of the tests that were specified using by +[\fBconfigure -match\fR] (userSpecifiedNonMatch) or matches any of +the tests specified by [\fBconfigure -skip\fR] (userSpecifiedSkip). Also +print warnings about possible lack of cleanup or balance in test files. .IP 2 Display the flag array parsed by the command line processor, the contents of the ::env array, and all user-defined variables that exist @@ -676,319 +746,115 @@ in the current namespace as they are used. Display information regarding what individual procs in the test harness are doing. .RE - .TP -\fBverbose\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: +\fB-verbose \fIlevel\fR +Sets the type of output verbosity desired to \fIlevel\fR, +a list of zero or more of the elements \fBbody\fR, \fBpass\fR, +\fBskip\fR, \fBstart\fR, and \fBerror\fR. Default value is \fBbody\fR. +Levels are defined as: .RS -.IP body +.IP body (b) Display the body of failed tests -.IP pass +.IP pass (p) Print output when a test passes -.IP skip +.IP skip (s) Print output when a test is skipped -.IP start +.IP start (t) Print output whenever a test starts -.IP error +.IP error (e) 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 -Sets or returns the current core preservation level. This level -determines how stringent checks for core files are. The default core -preservation level is 0. Levels are defined as: +The single letter abbreviations noted above are also recognized +so that [\fBconfigure -verbose pt\fR] is the same as +[\fBconfigure -verbose {pass start}\fR]. +.TP +\fB-preservecore \fIlevel\fR +Sets the core preservation level to \fIlevel\fR. This level +determines how stringent checks for core files are. Default +value is 0. Levels are defined as: .RS .IP 0 No checking - do not check for core files at the end of each test -command, but do check for them whenever tcltest::cleanupTests is -called from tcltest::runAllTests. +command, but do check for them in [\fBrunAllTests\fR] after all +test files have been evaluated. .IP 1 -Check for core files at the end of each test command and whenever -tcltest::cleanupTests is called from tcltest::runAllTests. +Also check for core files at the end of each [\fBtest\fR] command. .IP 2 -Check for core files at the end of all test commands and whenever -tcltest::cleanupTests is called from all.tcl. Save any core files -produced in tcltest::temporaryDirectory. +Check for core files at all times described above, and save a +copy of each core file produced in [\fBconfigure -tmpdir\fR]. .RE - -.TP -\fBtcltest::limitConstraints \fI?value?\fR -Sets or returns a boolean indicating whether testing is being limited -to the list of constraints specified by the \fB-constraints\fR -command line option. If \fIvalue\fR is true, only those tests -with constraints present in the list specified in the \fB-constraints\fR -command line option. - -.TP -\fBtcltest::temporaryDirectory\fR \fI?directoryName?\fR -Sets or returns the output directory for temporary files created by -tcltest::makeFile and tcltest::makeDirectory. This defaults to the -directory returned by \fItcltest::workingDirectory\fR. - -.TP -\fBtcltest::testsDirectory\fR \fI?directoryName?\fR -Sets or returns the directory where the tests reside. This defaults -to the directory returned by \fItcltest::workingDirectory\fR -if the script cannot determine where the \fItests\fR directory is -located. This variable should be explicitly set if tests are being run -from an all.tcl file. - -.TP -\fBtcltest::match\fR \fI?globPatternList?\fR -Sets or returns the glob pattern list that determines which tests -should be run. Only tests which match one of the glob patterns in -\fIglobPatternList\fR are run by the test harness. The default value -for \fIglobPatternList\fR is '*'. - -.TP -\fBtcltest::matchFiles\fR \fI?globPatternList?\fR -Sets or returns the glob pattern list that determines which test files -should be run. Only test files which match one of the glob patterns in -\fIglobPatternList\fR are run by the test harness. The default value -for \fIglobPatternList\fR is '*.test'. - -.TP -\fBtcltest::matchDirectories\fR \fI?globPatternList?\fR -Sets or returns the glob pattern list that determines which test -subdirectories of the current test directory should be run. Only test -subdirectories which match one of the glob patterns in -\fIglobPatternList\fR are run by the test harness. The default value -for \fIglobPatternList\fR is '*'. - -.TP -\fBtcltest::skip\fR \fI?globPatternList?\fR -Sets or returns the glob pattern list that determines which tests (of -those matched by tcltest::match) should be skipped. The default value -for \fIglobPatternList\fR is {}. - -.TP -\fBtcltest::skipFiles\fR \fI?globPatternList?\fR -Sets or returns the glob pattern list that determines which test files -(of those matched by tcltest::matchFiles) should be skipped. The -default value for \fIglobPatternList\fR is {}. - -.TP -\fBtcltest::skipDirectories\fR \fI?globPatternList?\fR -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::loadScript\fR \fI?script?\fR -Sets or returns the script executed by \fBloadTestedCommands\fR. - -.TP -\fBtcltest::loadFile\fR \fI?filename?\fR -Sets ore returns the file name associated with the script executed -\fBloadTestedCommands\fR. If setting \fIfilename\fR, this proc will -open the file and call \fItcltest::loadScript\fR with the content. - -.TP -\fBtcltest::outputFile\fR \fI?filename?\fR -Sets or returns the file name corresponding to the output file. This -defaults to stdout. This proc calls -outputChannel to set the output file channel. -Any test that prints test related output should send -that output to \fItcltest::outputChannel\fR rather than letting -that output default to stdout. - .TP -\fBtcltest::errorFile\fR \fI?filename?\fR -Sets or returns the file name corresponding to the error file. This -defaults to stderr. This proc calls -errorChannel to set the error file channel. -Any test that prints test related error output should send -that output to \fItcltest::errorChannel\fR or -\fItcltest::outputChannel\fR rather than letting -that output default to stdout. +\fB-limitconstraints \fIboolean\fR +Sets the mode by which [\fBtest\fR] honors constraints as described +in TESTS above. Default value is false. +.TP +\fB-constraints \fIlist\fR +Sets all the constraints in \fIlist\fR to true. Also used in +combination with \fB-limitconstraints true\fR to control an +alternative constraint mode as described in TESTS above. Default +value is an empty list. +.TP +\fB-tmpdir \fIdirectory\fR +Sets the temporary directory to be used by [\fBmakeFile\fR], +[\fBmakeDirectory\fR], [\fBviewFile\fR], [\fBremoveFile\fR], +and [\fBremoveDirectory\fR] as the default directory where +temporary files and directories created by test files should +be created. Default value is [\fBworkingDirectory\fR]. +.TP +\fB-testdir \fIdirectory\fR +Sets the directory searched by [\fBrunAllTests\fR] for test files +and subdirectories. Default value is [\fBworkingDirectory\fR]. +.TP +\fB-file \fIpatternList\fR +Sets the list of patterns used by [\fBrunAllTests\fR] to determine +what test files to evaluate. Default value is \fB*.test\fR. +.TP +\fB-notfile \fBpatternList\fR +Sets the list of patterns used by [\fBrunAllTests\fR] to determine +what test files to skip. Default value is \fBl.*.test\fR, so +that any SCCS lock files are skipped. +.TP +\fB-relateddir \fBpatternList\fR +Sets the list of patterns used by [\fBrunAllTests\fR] to determine +what subdirectories to search for an \fBall.tcl\fR file. Default +value is \fB*\fR. +.TP +\fB-asidefromdir \fBpatternList\fR +Sets the list of patterns used by [\fBrunAllTests\fR] to determine +what subdirectories to skip when searching for an \fBall.tcl\fR file. +Default value is an empty list. +.TP +\fB-match \fIpatternList\fR +Set the list of patterns used by [\fBtest\fR] to determine whether +a test should be run. Default value is \fB*\fR. +.TP +\fB-skip \fIpatternList\fR +Set the list of patterns used by [\fBtest\fR] to determine whether +a test should be skipped. Default value is an empty list. +.TP +\fB-load \fIscript\fR +Sets a script to be evaluated by [\fBloadTestedCommands\fR]. +Default value is an empty script. +.TP +\fB-loadfile \fIfilename\fR +Sets the filename from which to read a script to be evaluated +by [\fBloadTestedCommands\fR]. This is an alternative to +\fB-load\fR. They cannot be used together. +.TP +\fB-outfile \fIfilename\fR +Sets the file to which all output produced by tcltest should be +written. A file named \fIfilename\fR will be [\fBopen\fR]ed for writing, +and the resulting channel will be set as the value of [\fBoutputChannel\fR]. +.TP +\fB-errfile \fIfilename\fR +Sets the file to which all error output produced by tcltest +should be written. A file named \fIfilename\fR will be [\fBopen\fR]ed +for writing, and the resulting channel will be set as the value +of [\fBerrorChannel\fR]. .SH "CREATING TEST SUITES WITH TCLTEST" - -.SH "RUNNING TEST FILES" -Use the following command to run a test file that uses package -tcltest: -.CS -<shell> <testFile> ?<option> ?<value>?? ... -.CE -Command line options include (tcltest accessor procs that -correspond to each flag are listed at the end of each flag description -in parenthesis): -.RS -.TP -\fB-help\fR -display usage information. -.TP -\fB-singleproc <bool>\fR -if <bool> is 0, run test files in separate interpreters. if 1, source test -files into the current interpreter. (tcltest::singleProcess) -.TP -\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 -<matchList>. (tcltest::match) -.TP -\fB-skip <skipList>\fR -do not run tests that match one or more of the glob patterns in -<skipList>. (tcltest::skip) -.TP -\fB-file <globPatternList>\fR -only source test files that match any of the items in -<globPatternList> relative to tcltest::testsDirectory. -This option -only makes sense if you are running tests using "all.tcl" as the -<testFile> instead of running single test files directly. -(tcltest::matchFiles) -.TP -\fB-notfile <globPatternList>\fR -source files except for those that match any of the items in -<globPatternList> relative to tcltest::testsDirectory. -This option -only makes sense if you are running tests using "all.tcl" as the -<testFile> instead of running single test files directly. -(tcltest::skipFiles) -.TP -\fB-relateddir <globPatternList>\fR -only run tests in directories that match any of the items in -<globPatternList> relative to tcltest::testsDirectory. -This option -only makes sense if you are running tests using "all.tcl" as the -<testFile> instead of running single test files directly. -(tcltest::matchDirectories) -.TP -\fB-asidefromdir <globPatternList>\fR -run tests in directories except for those that match any of the items in -<globPatternList> relative to tcltest::testsDirectory. -This option -only makes sense if you are running tests using "all.tcl" as the -<testFile> instead of running single test files directly. -(tcltest::skipDirectories) -.TP -\fB-constraints <list>\fR -tests with any constraints in <list> will not be skipped. Note that -elements of <list> must exactly match the existing constraints. This -is useful if you want to make sure that tests with a particular -constraint are run (for example, if the tester wants to run all tests -with the knownBug constraint). -(tcltest::testConstraint) -.TP -\fB-limitconstraints <bool>\fR -If the argument to this flag is 1, the test harness limits test runs -to those tests that match the constraints listed by the -constraints -flag. Use of this flag requires use of the -constraints flag. The -default value for this flag is 0 (false). This is useful if you want -to run \fBonly\fR those tests that match the constraints listed using -the -constraints option. A tester might want to do this if (for -example) he were -interested in running only those tests that are constrained to be -unixOnly and no other tests. -(tcltest::limitConstraints) -.TP -\fB-load <script>\fR -will use the specified script to load the commands under test -(tcltest::loadTestedCommands). The default is the empty -script. See -loadfile below too. (tcltest::loadScript) -.TP -\fB-loadfile <scriptfile>\fR -will use the contents of the named file to load the commands under -test (tcltest::loadTestedCommands). See -load above too. The default -is the empty script. (tcltest::loadFile) -.TP -\fB-tmpdir <directoryName>\fR -put any temporary files (created with tcltest::makeFile and -tcltest::makeDirectory) into the named directory. The default -location is tcltest::workingDirectory. (tcltest::temporaryDirectory) -.TP -\fB-testdir <directoryName>\fR -search the test suite to execute in the named directory. The default -location is tcltest::workingDirectory. (tcltest::testsDirectory) -.TP -\fB-preservecore <level>\fR -check for core files. This flag is used to determine how much -checking should be done for core files. (tcltest::preserveCore) -.TP -\fB-debug <debugLevel>\fR -print debug information to stdout. This is used to debug code in the -tcltest package. (tcltest::debug) -.TP -\fB-outfile <filename>\fR -print output generated by the tcltest package to the named file. This -defaults to stdout. Note that debug output always goes to stdout, -regardless of this flag's setting. (tcltest::outputFile) -.TP -\fB-errfile <filename>\fR -print errors generated by the tcltest package to the named file. This -defaults to stderr. (tcltest::errorFile) -.RE -.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 '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 tests is to start up a shell, load the -\fBtcltest\fR package, and then source an appropriate test file or use -the test command. To use the options in interactive mode, set -their corresponding tcltest namespace variables after loading the -package. -.PP -See \fI"Test Constraints"\fR for a list of all built-in constraint names. -.PP -A final way to run tests would be to specify which test files to run -within an \fIall.tcl\fR (or otherwise named) file. This is the -approach used by the Tcl test suite. This file loads the tcltest -package, sets the location of -the test directory (tcltest::testsDirectory), and then calls the -\fItcltest::runAllTests\fR proc, which determines which test -files to run, how to run them, and calls tcltest::cleanupTests to -determine the summary status of the test suite. -.PP -A more elaborate \fIall.tcl\fR file might do some pre- and -post-processing before sourcing -each .test file, use separate interpreters for each file, or handle -complex directory structures. -For an example of an all.tcl file, -please see the "Examples" section of this document. - -.SH "TEST OUTPUT" -After all specified test files are run, the number of tests -passed, skipped, and failed is printed to -\fBtcltest::outputChannel\fR. Aside from this -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 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 "skip" is present, then a line (containing -the constraints that cause the test to be skipped) is printed for each -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: -.CS -tclsh socket.test -verbose 'body pass skip' -.CE - .SH "CONTENTS OF A TEST FILE" Test files should begin by loading the \fBtcltest\fR package: .CS @@ -1012,89 +878,6 @@ 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. For example, the test file for the C file "tclCmdAH.c" is "cmdAH.test". -.SH "SELECTING TESTS FOR EXECUTION" -.PP -Normally, all the tests in a file are run whenever the file is -sourced. An individual test will be skipped if one of the following -conditions is met: -.IP [1] -the \fIname\fR of the tests does not match (using glob style matching) -one or more elements in the \fBtcltest::match\fR variable -.IP [2] -the \fIname\fR of the tests matches (using glob style matching) one or -more elements in the \fBtcltest::skip\fR variable -.IP [3] -the \fIconstraints\fR argument to the \fBtcltest::test\fR call, if -given, contains one or more false elements. -.PP -You can set \fBtcltest::match\fR and/or \fBtcltest::skip\fR -either interactively (after the \fBtcltest\fR package has been -sourced), or by using the command line arguments \fB-match\fR and -\fB-skip\fR, for example: -.PP -.CS -tclsh info.test -match '*-5.* *-7.*' -skip '*-7.1*' -.CE -.PP -Be sure to use the proper quoting convention so that your shell does -not perform the glob substitution on the match or skip patterns you -specify. -.PP -Predefined constraints (e.g. \fIknownBug\fR and \fInonPortable\fR) can be -overridden either interactively (after the \fBtcltest\fR package has been -sourced) by setting the proper constraint -or by using the \fB-constraints\fR command line option with the name of the -constraint in the argument. The following example shows how to run -tests that are constrained by the \fIknownBug\fR and \fInonPortable\fR -restrictions: -.PP -.CS -tclsh all.tcl -constraints "knownBug nonPortable" -.CE -.PP -See the \fI"Constraints"\fR section for information about using -built-in constraints and adding new ones. -.PP -When tests are run from within an \fBall.tcl\fR file, all files with a -``\fI.test\fR'' extension are normally run. An individual test file will -be skipped if one of the following conditions is met: -.IP [1] -the \fIname\fR of the test files does not match (using glob style matching) -one or more elements in the \fBtcltest::matchFiles\fR variable -.IP [2] -the \fIname\fR of the test file matches (using glob style matching) one or -more elements in the \fBtcltest::skipFiles\fR variable -.PP -You can set \fBtcltest::matchFiles\fR and/or \fBtcltest::skipFiles\fR -either interactively (after the \fBtcltest\fR package has been -sourced), or by using the command line arguments \fB-file\fR and -\fB-notfile\fR, for example: -.PP -.CS -tclsh info.test -file 'unix*.test' -notfile 'unixNotfy.test' -.CE -.PP -Additionally, if tests are run from within an 'all.tcl' containing a -call to \fBtcltest::runAllTests\fR, any subdirectory of -\fItcltest::testsDirectory\fR containing an 'all.tcl' file will also -be run. Individual test subdirectories will be skipped if one of the -following conditions is met: -.IP [1] -the \fIname\fR of the directory does not match (using glob style matching) -one or more elements in the \fBtcltest::matchDirectories\fR variable -.IP [2] -the \fIname\fR of the directory matches (using glob style matching) one or -more elements in the \fBtcltest::skipDirectories\fR variable -.PP -You can set \fBtcltest::matchDirectories\fR and/or \fBtcltest::skipDirectories\fR -either interactively (after the \fBtcltest\fR package has been -sourced), or by using the command line arguments \fB-relateddir\fR and -\fB-asidefromdir\fR, for example: -.PP -.CS -tclsh info.test -relateddir 'subdir*' -asidefromdir 'subdir2' -.CE - .SH "HOW TO CUSTOMIZE THE TEST HARNESS" To create your own custom test harness, create a .tcl file that contains your namespace. Within this file, require package \fBtcltest\fR. Commands @@ -1172,7 +955,6 @@ test testOnUnixWithoutThreads-1.1 { .SH COMPATIBILITY - .SH "KNOWN ISSUES" There are two known issues related to nested evaluations of [\fBtest\fR]. The first issue relates to the stack level in which test scripts are |