777 lines
38 KiB
HTML
777 lines
38 KiB
HTML
|
<HTML><HEAD><TITLE>Tcl Built-In Commands - Tcltest manual page</TITLE></HEAD><BODY>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M2" NAME="L1169">NAME</A>
|
||
|
|
<DL><DD>Tcltest - Test harness support code and utilities</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M3" NAME="L1170">SYNOPSIS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><B>package require tcltest ?1.0?</B>
|
||
|
|
<DD><B>::tcltest::test </B><I>name desc ?constraint? script expectedAnswer</I>
|
||
|
|
<DD><B>::tcltest::cleanupTests </B><I>?runningMultipleTests?</I>
|
||
|
|
<DD><B>::tcltest::getMatchingTestFiles</B>
|
||
|
|
<DD><B>::tcltest::loadTestedCommands</B>
|
||
|
|
<DD><B>::tcltest::makeFile </B><I>contents name</I>
|
||
|
|
<DD><B>::tcltest::removeFile </B><I>name</I>
|
||
|
|
<DD><B>::tcltest::makeDirectory </B><I>name</I>
|
||
|
|
<DD><B>::tcltest::removeDirectory </B><I>name</I>
|
||
|
|
<DD><B>::tcltest::viewFile </B><I>name</I>
|
||
|
|
<DD><B>::tcltest::normalizeMsg </B><I>msg</I>
|
||
|
|
<DD><B>::tcltest::bytestring </B><I>string</I>
|
||
|
|
<DD><B>::tcltest::saveState</B>
|
||
|
|
<DD><B>::tcltest::restoreState</B>
|
||
|
|
<DD><B>::tcltest::threadReap</B>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M4" NAME="L1171">DESCRIPTION</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M5" NAME="L1172">COMMANDS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M6" NAME="L1173"><B>::tcltest::test</B> <I>name desc ?constraints? script expectedAnswer</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M7" NAME="L1174"><B>::tcltest::cleanupTests</B> <I>?runningMultipleTests?</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M8" NAME="L1175"><B>::tcltest::getMatchingTestFiles</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M9" NAME="L1176"><B>::tcltest::loadTestedCommands</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M10" NAME="L1177"><B>::tcltest::makeFile</B> <I>contents name</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M11" NAME="L1178"><B>::tcltest::removeFile</B> <I>name</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M12" NAME="L1179"><B>::tcltest::makeDirectory</B> <I>name</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M13" NAME="L1180"><B>::tcltest::removeDirectory</B> <I>name</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M14" NAME="L1181"><B>::tcltest::viewFile</B> <I>file</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M15" NAME="L1182"><B>::tcltest::normalizeMsg</B> <I>msg</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M16" NAME="L1183"><B>::tcltest::bytestring</B> <I>string</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M17" NAME="L1184"><B>::tcltest::saveState</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M18" NAME="L1185"><B>::tcltest::threadReap</B></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M19" NAME="L1186">TESTS</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M20" NAME="L1187">TCLTEST NAMEPSACE VARIABLES</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M21" NAME="L1188"><B>::tcltest::outputChannel</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M22" NAME="L1189"><B>::tcltest::errorChannel</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M23" NAME="L1190"><B>::tcltest::mainThread</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M24" NAME="L1191"><B>::tcltest::originalEnv</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M25" NAME="L1192"><B>::tcltest::workingDirectory</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M26" NAME="L1193"><B>::tcltest::temporaryDirectory</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M27" NAME="L1194"><B>::tcltest::testsDirectory</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M28" NAME="L1195"><B>::tcltest::tcltest</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M29" NAME="L1196"><B>::tcltest::loadScript</B></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M30" NAME="L1197">TEST CONSTRAINTS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M31" NAME="L1198"><I>unix</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M32" NAME="L1199"><I>pc</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M33" NAME="L1200"><I>nt</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M34" NAME="L1201"><I>95</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M35" NAME="L1202"><I>98</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M36" NAME="L1203"><I>mac</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M37" NAME="L1204"><I>unixOrPc</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M38" NAME="L1205"><I>macOrPc</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M39" NAME="L1206"><I>macOrUnix</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M40" NAME="L1207"><I>tempNotPc</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M41" NAME="L1208"><I>tempNotMac</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M42" NAME="L1209"><I>unixCrash</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M43" NAME="L1210"><I>pcCrash</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M44" NAME="L1211"><I>macCrash</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M45" NAME="L1212"><I>emptyTest</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M46" NAME="L1213"><I>knownBug</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M47" NAME="L1214"><I>nonPortable</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M48" NAME="L1215"><I>userInteraction</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M49" NAME="L1216"><I>interactive</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M50" NAME="L1217"><I>nonBlockFiles</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M51" NAME="L1218"><I>asyncPipeClose</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M52" NAME="L1219"><I>unixExecs</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M53" NAME="L1220"><I>hasIsoLocale</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M54" NAME="L1221"><I>root</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M55" NAME="L1222"><I>notRoot</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M56" NAME="L1223"><I>eformat</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M57" NAME="L1224"><I>stdio</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M58" NAME="L1225">RUNNING TEST FILES</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M59" NAME="L1226"><B>-help</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M60" NAME="L1227"><B>-verbose <level></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M61" NAME="L1228"><B>-match <matchList></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M62" NAME="L1229"><B>-skip <skipList></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M63" NAME="L1230"><B>-file <globPatternList></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M64" NAME="L1231"><B>-notfile <globPatternList></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M65" NAME="L1232"><B>-constraints <list></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M66" NAME="L1233"><B>-limitconstraints <bool></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M67" NAME="L1234"><B>-load <script></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M68" NAME="L1235"><B>-loadfile <scriptfile></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M69" NAME="L1236"><B>-tmpdir <directoryName></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M70" NAME="L1237"><B>-testdir <directoryName></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M71" NAME="L1238"><B>-preservecore <level></B></A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M72" NAME="L1239">0</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M73" NAME="L1240">1</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M74" NAME="L1241">2</A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M75" NAME="L1242"><B>-debug <debugLevel></B></A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M76" NAME="L1243">0</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M77" NAME="L1244">1</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M78" NAME="L1245">2</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M79" NAME="L1246">3</A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M80" NAME="L1247"><B>-outfile <filename></B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M81" NAME="L1248"><B>-errfile <filename></B></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M82" NAME="L1249">TEST OUTPUT</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M83" NAME="L1250">CONTENTS OF A TEST FILE</A>
|
||
|
|
<DD><A HREF="tcltest.htm#M84" NAME="L1251">SELECTING TESTS FOR EXECUTION WITHIN A FILE</A>
|
||
|
|
<DL>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M85" NAME="L1252">HOW TO CUSTOMIZE THE TEST HARNESS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M86" NAME="L1253"><B>::tcltest::PrintUsageInfoHook</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M87" NAME="L1254"><B>::tcltest::processCmdLineArgsFlagHook</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M88" NAME="L1255"><B>::tcltest::processCmdLineArgsHook</B> <I>flags</I></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M89" NAME="L1256"><B>::tcltest::initConstraintsHook</B></A>
|
||
|
|
<DD><A HREF="tcltest.htm#M90" NAME="L1257"><B>::tcltest::cleanupTestsHook</B></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M91" NAME="L1258">EXAMPLES</A>
|
||
|
|
<DL>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="tcltest.htm#M92" NAME="L1259">KEYWORDS</A>
|
||
|
|
</DL><HR>
|
||
|
|
<H3><A NAME="M2">NAME</A></H3>
|
||
|
|
Tcltest - Test harness support code and utilities
|
||
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||
|
|
<B>package require tcltest ?1.0?</B><BR>
|
||
|
|
<B>::tcltest::test </B><I>name desc ?constraint? script expectedAnswer</I><BR>
|
||
|
|
<B>::tcltest::cleanupTests </B><I>?runningMultipleTests?</I><BR>
|
||
|
|
<B>::tcltest::getMatchingTestFiles</B><BR>
|
||
|
|
<B>::tcltest::loadTestedCommands</B><BR>
|
||
|
|
<B>::tcltest::makeFile </B><I>contents name</I><BR>
|
||
|
|
<B>::tcltest::removeFile </B><I>name</I><BR>
|
||
|
|
<B>::tcltest::makeDirectory </B><I>name</I><BR>
|
||
|
|
<B>::tcltest::removeDirectory </B><I>name</I><BR>
|
||
|
|
<B>::tcltest::viewFile </B><I>name</I><BR>
|
||
|
|
<B>::tcltest::normalizeMsg </B><I>msg</I><BR>
|
||
|
|
<B>::tcltest::bytestring </B><I>string</I><BR>
|
||
|
|
<B>::tcltest::saveState</B><BR>
|
||
|
|
<B>::tcltest::restoreState</B><BR>
|
||
|
|
<B>::tcltest::threadReap</B><BR>
|
||
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||
|
|
The <B>tcltest</B> 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.
|
||
|
|
<P>
|
||
|
|
The Tcl test suite consists of multiple .test files, each of which
|
||
|
|
contains multiple test cases. Each test case consists of a call to
|
||
|
|
the test command, which specifies the name of test, a short
|
||
|
|
description, any constraints that apply to the test case, the script
|
||
|
|
to be run, and expected results. See the sections <I>"Tests,"</I>
|
||
|
|
<I>"Test Constraints,"</I> and <I>"Test Files and How to Run Them"</I>
|
||
|
|
for more details.
|
||
|
|
<P>
|
||
|
|
It is also possible to add to this test harness to create your own
|
||
|
|
customized test harness implementation. For more defails, see the
|
||
|
|
section <I>"How to Customize the Test Harness"</I>.
|
||
|
|
<P>
|
||
|
|
This approach to testing was designed and initially implemented by
|
||
|
|
Mary Ann May-Pumphrey of Sun Microsystems in the early 1990's. Many
|
||
|
|
thanks to her for donating her work back to the public Tcl release.
|
||
|
|
<H3><A NAME="M5">COMMANDS</A></H3>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M6"><B>::tcltest::test</B> <I>name desc ?constraints? script expectedAnswer</I></A><DD>
|
||
|
|
The <B>::tcltest::test</B> command runs<I>script</I> and compares
|
||
|
|
its result to <I>expectedAnswer</I>. It prints an error message if the two do
|
||
|
|
not match. If <B>::tcltest::verbose</B> contains "p" or "s", it also prints
|
||
|
|
out a message if the test passed or was skipped. The test will be
|
||
|
|
skipped if it doesn't match the <B>::tcltest::match</B> variable, if it
|
||
|
|
matches an element in <B>::tcltest::skip</B>, or if one of the elements
|
||
|
|
of <I>constraint</I> turns out not to be true. The
|
||
|
|
<B>::tcltest::test</B> command has no defined return values. See the
|
||
|
|
<I>"Writing a new test"</I> section for more details on this command.
|
||
|
|
<P><DT><A NAME="M7"><B>::tcltest::cleanupTests</B> <I>?runningMultipleTests?</I></A><DD>
|
||
|
|
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
|
||
|
|
<B>::tcltest::makeDirectory</B> and <B>::tcltest::makeFile</B>. Names
|
||
|
|
of files and directories created outside of
|
||
|
|
<B>::tcltest::makeFile</B> and <B>::tcltest::makeDirectory</B> and
|
||
|
|
never deleted are printed to <B>::tcltest::outputChannel</B>. This command
|
||
|
|
also restores the original shell environment, as described by the ::env
|
||
|
|
array. <I>calledFromAll</I> should be specified when
|
||
|
|
<B>::tcltest::cleanupTests</B> is called from an "all.tcl" file. Tcl files
|
||
|
|
files are generally used to run multiple tests. For more details on how to
|
||
|
|
run multiple tests, please see the section <I>"Running test files"</I>.
|
||
|
|
This proc has no defined return value.
|
||
|
|
<P><DT><A NAME="M8"><B>::tcltest::getMatchingTestFiles</B></A><DD>
|
||
|
|
This command is used when you want to run multiple test files. It returns
|
||
|
|
the list of tests that should be sourced in an 'all.tcl' file. See the
|
||
|
|
section <I>"Running test files"</I> for more information.
|
||
|
|
<P><DT><A NAME="M9"><B>::tcltest::loadTestedCommands</B></A><DD>
|
||
|
|
This command uses the script specified via the <I>-load</I> or
|
||
|
|
<I>-loadfile</I> to load the commands checked by the test suite.
|
||
|
|
Allowed to be empty, as the tested commands could have been compiled
|
||
|
|
into the interpreter running the test suite.
|
||
|
|
<P><DT><A NAME="M10"><B>::tcltest::makeFile</B> <I>contents name</I></A><DD>
|
||
|
|
Create a file that will be automatically be removed by
|
||
|
|
<B>::tcltest::cleanupTests</B> at the end of a test file.
|
||
|
|
This proc has no defined return value.
|
||
|
|
<P><DT><A NAME="M11"><B>::tcltest::removeFile</B> <I>name</I></A><DD>
|
||
|
|
Force the file referenced by <I>name</I> to be removed. This file name
|
||
|
|
should be relative to <I>::tcltest::temporaryDirectory</I>. This proc has no
|
||
|
|
defined return values.
|
||
|
|
<P><DT><A NAME="M12"><B>::tcltest::makeDirectory</B> <I>name</I></A><DD>
|
||
|
|
Create a directory named <I>name</I> that will automatically be removed
|
||
|
|
by <B>::tcltest::cleanupTests</B> at the end of a test file. This proc
|
||
|
|
has no defined return value.
|
||
|
|
<P><DT><A NAME="M13"><B>::tcltest::removeDirectory</B> <I>name</I></A><DD>
|
||
|
|
Force the directory referenced by <I>name</I> to be removed. This proc
|
||
|
|
has no defined return value.
|
||
|
|
<P><DT><A NAME="M14"><B>::tcltest::viewFile</B> <I>file</I></A><DD>
|
||
|
|
Returns the contents of <I>file</I>.
|
||
|
|
<P><DT><A NAME="M15"><B>::tcltest::normalizeMsg</B> <I>msg</I></A><DD>
|
||
|
|
Remove extra newlines from <I>msg</I>.
|
||
|
|
<P><DT><A NAME="M16"><B>::tcltest::bytestring</B> <I>string</I></A><DD>
|
||
|
|
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 <I>string</I>. This allows the tester to create
|
||
|
|
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.
|
||
|
|
<P><DT><A NAME="M17"><B>::tcltest::saveState</B></A><DD>
|
||
|
|
<B>::tcltest::restoreState</B>
|
||
|
|
Save and restore the procedure and global variable names.
|
||
|
|
A test file might contain calls to <B>::tcltest::saveState</B> and
|
||
|
|
<B>::tcltest:restoreState</B> if it creates or deletes global variables
|
||
|
|
or procs.
|
||
|
|
<P><DT><A NAME="M18"><B>::tcltest::threadReap</B></A><DD>
|
||
|
|
<B>::tcltest::threadReap</B> only works if <I>testthread</I> is
|
||
|
|
defined, generally by compiling tcltest. If <I>testthread</I> is
|
||
|
|
defined, <B>::tcltest::threadReap</B> kills all threads except for the
|
||
|
|
main thread. It gets the ID of the main thread by calling
|
||
|
|
<I>testthread names</I> during initialization. This value is stored in
|
||
|
|
<I>::tcltest::mainThread</I>. <B>::tcltest::threadReap</B> returns the
|
||
|
|
number of existing threads at completion.
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M19">TESTS</A></H3>
|
||
|
|
The <B>test</B> procedure runs a test script and prints an error
|
||
|
|
message if the script's result does not match the expected result.
|
||
|
|
The following is the spec for the <B>test</B> command:
|
||
|
|
<PRE>test <name> <description> ?<constraint>? <script> <expectedAnswer></PRE>
|
||
|
|
The <name> argument should follow the pattern:
|
||
|
|
<PRE><target>-<majorNum>.<minorNum></PRE>
|
||
|
|
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
|
||
|
|
should share a major number.
|
||
|
|
<P>
|
||
|
|
The <description> argument is a short textual description of the test,
|
||
|
|
to help humans understand what it tests. The name of a Tcl or C
|
||
|
|
function being tested should be included for regression tests. If the
|
||
|
|
test case exists to reproduce a bug, include the bug ID in the
|
||
|
|
description.
|
||
|
|
<P>
|
||
|
|
The optional <constraints> argument can be list of one or more
|
||
|
|
keywords or an expression. If the <constraints> argument consists of
|
||
|
|
keywords, each of these keywords must be the name of an element in the array
|
||
|
|
<I>::tcltest::testConstraints</I>. If any of these elements is false or does
|
||
|
|
not exist, the test is skipped. If the <constraints> argument
|
||
|
|
consists of an expression, that expression is evaluated. If the
|
||
|
|
expression evaluates to true, then the test is run.
|
||
|
|
<P>
|
||
|
|
Add appropriate constraints (e.g.,
|
||
|
|
unixOnly) to any tests that should not always be run. For example, a
|
||
|
|
test that should only be run on Unix should look like the following:
|
||
|
|
<P>
|
||
|
|
<PRE>test getAttribute-1.1 {testing file permissions} {unixOnly} {
|
||
|
|
lindex [file attributes foo.tcl] 5
|
||
|
|
} {00644}</PRE>
|
||
|
|
<P>
|
||
|
|
An example of a test that contains an expression:
|
||
|
|
<P>
|
||
|
|
<PRE>test unixNotfy-1.1 {<A HREF="../TkLib/CrtFileHdlr.htm">Tcl_DeleteFileHandler</A>} {unixOnly && !testthread} {
|
||
|
|
catch {vwait x}
|
||
|
|
set f [open foo w]
|
||
|
|
fileevent $f writable {set x 1}
|
||
|
|
vwait x
|
||
|
|
close $f
|
||
|
|
list [catch {vwait x} msg] $msg
|
||
|
|
} {1 {can't wait for variable "x": would wait forever}}</PRE>
|
||
|
|
<P>
|
||
|
|
See the "Test Constraints" section for a list of built-in
|
||
|
|
constraints and information on how to add your own constraints.
|
||
|
|
<P>
|
||
|
|
The <script> argument contains the script to run to carry out the
|
||
|
|
test. It must return a result that can be checked for correctness.
|
||
|
|
If your script requires that a file be created on the fly, please use
|
||
|
|
the ::tcltest::makeFile procedure. If your test requires that a small
|
||
|
|
file (<50 lines) be checked in, please consider creating the file on
|
||
|
|
the fly using the ::tcltest::makeFile procedure. Files created by the
|
||
|
|
::tcltest::makeFile procedure will automatically be removed by the
|
||
|
|
::tcltest::cleanupTests call at the end of each test file.
|
||
|
|
<P>
|
||
|
|
The <expectedAnswer> argument will be compared against the result of
|
||
|
|
evaluating the <script> argument. If they match, the test passes,
|
||
|
|
otherwise the test fails.
|
||
|
|
<H3><A NAME="M20">TCLTEST NAMEPSACE VARIABLES</A></H3>
|
||
|
|
The following variables are also defined in the <B>tcltest</B> namespace and
|
||
|
|
can be used by tests:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M21"><B>::tcltest::outputChannel</B></A><DD>
|
||
|
|
output file ID - defaults to stdout and can be specified using
|
||
|
|
-outfile on the command line.
|
||
|
|
Any test that prints test related output should send
|
||
|
|
that output to <I>::tcltest::outputChannel</I> rather than letting
|
||
|
|
that output default to stdout.
|
||
|
|
<P><DT><A NAME="M22"><B>::tcltest::errorChannel</B></A><DD>
|
||
|
|
error file ID - defaults to stderr and can be specified using -errfile
|
||
|
|
on the command line.
|
||
|
|
Any test that prints error messages should send
|
||
|
|
that output to <I>::tcltest::errorChannel</I> rather than printing
|
||
|
|
directly to stderr.
|
||
|
|
<P><DT><A NAME="M23"><B>::tcltest::mainThread</B></A><DD>
|
||
|
|
main thread ID - defaults to 1. This is the only thread that is not
|
||
|
|
killed by ::tcltest::threadReap and is set according to the return
|
||
|
|
value of <I>testthread names</I> at initialization.
|
||
|
|
<P><DT><A NAME="M24"><B>::tcltest::originalEnv</B></A><DD>
|
||
|
|
copy of the global "env" array at the beginning of the test run. This
|
||
|
|
array is used to restore the "env" array to its original state when
|
||
|
|
<I>::tcltest::cleanupTests</I> is called.
|
||
|
|
<P><DT><A NAME="M25"><B>::tcltest::workingDirectory</B></A><DD>
|
||
|
|
the directory in which the test suite was launched.
|
||
|
|
<P><DT><A NAME="M26"><B>::tcltest::temporaryDirectory</B></A><DD>
|
||
|
|
the output directory - defaults to <I>::tcltest::workingDirectory</I> and can be
|
||
|
|
specified using -tmpdir on the command line.
|
||
|
|
<P><DT><A NAME="M27"><B>::tcltest::testsDirectory</B></A><DD>
|
||
|
|
where the tests reside - defaults to <I>::tcltest::workingDirectory</I>
|
||
|
|
if the script cannot determine where the <I>tests</I> directory is
|
||
|
|
located. It is possible to change the default by specifying
|
||
|
|
<I>-testdir</I> on the commandline. This variable should be
|
||
|
|
explicitly set if tests are being run from an all.tcl file.
|
||
|
|
<P><DT><A NAME="M28"><B>::tcltest::tcltest</B></A><DD>
|
||
|
|
the name of the executable used to invoke the test suite.
|
||
|
|
<P><DT><A NAME="M29"><B>::tcltest::loadScript</B></A><DD>
|
||
|
|
The script executed <B>loadTestedCommands</B>. Specified either by
|
||
|
|
<I>-load</I> or <I>-loadfile</I>.
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M30">TEST CONSTRAINTS</A></H3>
|
||
|
|
Constraints are used to determine whether a test should be skipped.
|
||
|
|
Each constraint is stored as an index in the array
|
||
|
|
<I>::tcltest::testConstraints</I>. For example, the unixOnly constraint is
|
||
|
|
defined as the following:
|
||
|
|
<PRE>set ::tcltest::testConstraints(unixOnly) \
|
||
|
|
[string equal $tcl_platform(platform) "unix"]</PRE>
|
||
|
|
If a test is constrained by "unixOnly", then it will only be run if
|
||
|
|
the value of ::tcltest::testConstraints(unixOnly) is true. Several
|
||
|
|
constraints are defined in the <B>tcltest</B> package. To add file- or
|
||
|
|
test-specific constraints, you can set the desired index of the
|
||
|
|
::tcltest::testsConstraints array in your own test file.
|
||
|
|
<P>
|
||
|
|
The following is a list of constraints defined in the <B>tcltest</B> package:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M31"><I>unix</I></A><DD>
|
||
|
|
test can only be run on any UNIX platform
|
||
|
|
<P><DT><A NAME="M32"><I>pc</I></A><DD>
|
||
|
|
test can only be run on any Windows platform
|
||
|
|
<P><DT><A NAME="M33"><I>nt</I></A><DD>
|
||
|
|
test can only be run on any Windows NT platform
|
||
|
|
<P><DT><A NAME="M34"><I>95</I></A><DD>
|
||
|
|
test can only be run on any Windows 95 platform
|
||
|
|
<P><DT><A NAME="M35"><I>98</I></A><DD>
|
||
|
|
test can only be run on any Windows 98 platform
|
||
|
|
<P><DT><A NAME="M36"><I>mac</I></A><DD>
|
||
|
|
test can only be run on any Mac platform
|
||
|
|
<P><DT><A NAME="M37"><I>unixOrPc</I></A><DD>
|
||
|
|
test can only be run on a UNIX or PC platform
|
||
|
|
<P><DT><A NAME="M38"><I>macOrPc</I></A><DD>
|
||
|
|
test can only be run on a Mac or PC platform
|
||
|
|
<P><DT><A NAME="M39"><I>macOrUnix</I></A><DD>
|
||
|
|
test can only be run on a Mac or UNIX platform
|
||
|
|
<P><DT><A NAME="M40"><I>tempNotPc</I></A><DD>
|
||
|
|
test can not be run on Windows. This flag is used to temporarily
|
||
|
|
disable a test.
|
||
|
|
<P><DT><A NAME="M41"><I>tempNotMac</I></A><DD>
|
||
|
|
test can not be run on a Mac. This flag is used
|
||
|
|
to temporarily disable a test.
|
||
|
|
<P><DT><A NAME="M42"><I>unixCrash</I></A><DD>
|
||
|
|
test crashes if it's run on UNIX. This flag is used to temporarily
|
||
|
|
disable a test.
|
||
|
|
<P><DT><A NAME="M43"><I>pcCrash</I></A><DD>
|
||
|
|
test crashes if it's run on Windows. This flag is used to temporarily
|
||
|
|
disable a test.
|
||
|
|
<P><DT><A NAME="M44"><I>macCrash</I></A><DD>
|
||
|
|
test crashes if it's run on a Mac. This flag is used to temporarily
|
||
|
|
disable a test.
|
||
|
|
<P><DT><A NAME="M45"><I>emptyTest</I></A><DD>
|
||
|
|
test is empty, and so not worth running, but it remains as a
|
||
|
|
place-holder for a test to be written in the future. This constraint
|
||
|
|
always causes tests to be skipped.
|
||
|
|
<P><DT><A NAME="M46"><I>knownBug</I></A><DD>
|
||
|
|
test is known to fail and the bug is not yet fixed. This constraint
|
||
|
|
always causes tests to be skipped unless the user specifies otherwise.
|
||
|
|
See the "Introduction" section for more details.
|
||
|
|
<P><DT><A NAME="M47"><I>nonPortable</I></A><DD>
|
||
|
|
test can only be run in the master Tcl/Tk development environment.
|
||
|
|
Some tests are inherently non-portable because they depend on things
|
||
|
|
like word length, file system configuration, window manager, etc.
|
||
|
|
These tests are only run in the main Tcl development directory where
|
||
|
|
the configuration is well known. This constraint always causes tests
|
||
|
|
to be skipped unless the user specifies otherwise.
|
||
|
|
<P><DT><A NAME="M48"><I>userInteraction</I></A><DD>
|
||
|
|
test requires interaction from the user. This constraint always
|
||
|
|
causes tests to be skipped unless the user specifies otherwise.
|
||
|
|
<P><DT><A NAME="M49"><I>interactive</I></A><DD>
|
||
|
|
test can only be run in if the interpreter is in interactive mode,
|
||
|
|
that is the global tcl_interactive variable is set to 1.
|
||
|
|
<P><DT><A NAME="M50"><I>nonBlockFiles</I></A><DD>
|
||
|
|
test can only be run if platform supports setting files into
|
||
|
|
nonblocking mode
|
||
|
|
<P><DT><A NAME="M51"><I>asyncPipeClose</I></A><DD>
|
||
|
|
test can only be run if platform supports async flush and async close
|
||
|
|
on a pipe
|
||
|
|
<P><DT><A NAME="M52"><I>unixExecs</I></A><DD>
|
||
|
|
test can only be run if this machine has commands such as 'cat', 'echo',
|
||
|
|
etc. available.
|
||
|
|
<P><DT><A NAME="M53"><I>hasIsoLocale</I></A><DD>
|
||
|
|
test can only be run if can switch to an ISO locale
|
||
|
|
<P><DT><A NAME="M54"><I>root</I></A><DD>
|
||
|
|
test can only run if Unix user is root
|
||
|
|
<P><DT><A NAME="M55"><I>notRoot</I></A><DD>
|
||
|
|
test can only run if Unix user is not root
|
||
|
|
<P><DT><A NAME="M56"><I>eformat</I></A><DD>
|
||
|
|
test can only run if app has a working version of sprintf with respect
|
||
|
|
to the "e" format of floating-point numbers.
|
||
|
|
<P><DT><A NAME="M57"><I>stdio</I></A><DD>
|
||
|
|
test can only be run if the current app can be spawned via a pipe
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M58">RUNNING TEST FILES</A></H3>
|
||
|
|
Use the following command to run a test file that uses package
|
||
|
|
tcltest:
|
||
|
|
<PRE><shell> <testFile> ?<option> ?<value>?? ...</PRE>
|
||
|
|
Command line options include (tcltest namespace variables that
|
||
|
|
correspond to each flag are listed at the end of each flag description
|
||
|
|
in parenthesis):
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M59"><B>-help</B></A><DD>
|
||
|
|
display usage information.
|
||
|
|
<P><DT><A NAME="M60"><B>-verbose <level></B></A><DD>
|
||
|
|
set the level of verbosity to a substring of "bps". See the "Test
|
||
|
|
output" section for an explanation of this option. (::tcltest::verbose)
|
||
|
|
<P><DT><A NAME="M61"><B>-match <matchList></B></A><DD>
|
||
|
|
only run tests that match one or more of the glob patterns in
|
||
|
|
<matchList>. (::tcltest::match)
|
||
|
|
<P><DT><A NAME="M62"><B>-skip <skipList></B></A><DD>
|
||
|
|
do not run tests that match one or more of the glob patterns in
|
||
|
|
<skipList>. (::tcltest::skip)
|
||
|
|
<P><DT><A NAME="M63"><B>-file <globPatternList></B></A><DD>
|
||
|
|
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)
|
||
|
|
<P><DT><A NAME="M64"><B>-notfile <globPatternList></B></A><DD>
|
||
|
|
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)
|
||
|
|
<P><DT><A NAME="M65"><B>-constraints <list></B></A><DD>
|
||
|
|
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::testConstraints(<I>constraintName</I>))
|
||
|
|
<P><DT><A NAME="M66"><B>-limitconstraints <bool></B></A><DD>
|
||
|
|
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 <B>only</B> those tests that match the constraints listed using
|
||
|
|
the -constraints option. A tester might want to do this if he were
|
||
|
|
interested in running only those tests that are constrained to be
|
||
|
|
unixOnly and no other tests.
|
||
|
|
(::tcltest::limitConstraints)
|
||
|
|
<P><DT><A NAME="M67"><B>-load <script></B></A><DD>
|
||
|
|
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)
|
||
|
|
<P><DT><A NAME="M68"><B>-loadfile <scriptfile></B></A><DD>
|
||
|
|
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::loadScript)
|
||
|
|
<P><DT><A NAME="M69"><B>-tmpdir <directoryName></B></A><DD>
|
||
|
|
put any temporary files (created with ::tcltest::makeFile and
|
||
|
|
::tcltest::makeDirectory) into the named directory. The default
|
||
|
|
location is ::tcltest::workingDirectory. (::tcltest::temporaryDirectory)
|
||
|
|
<P><DT><A NAME="M70"><B>-testdir <directoryName></B></A><DD>
|
||
|
|
search the test suite to execute in the named directory. The default
|
||
|
|
location is ::tcltest::workingDirectory. (::tcltest::testsDirectory)
|
||
|
|
<P><DT><A NAME="M71"><B>-preservecore <level></B></A><DD>
|
||
|
|
check for core files. This flag is used to determine how much
|
||
|
|
checking should be done for core files. The default value for
|
||
|
|
<I>level</I> is 0. Levels are defined as:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M72">0</A><DD>
|
||
|
|
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 an all.tcl file.
|
||
|
|
<P><DT><A NAME="M73">1</A><DD>
|
||
|
|
Check for core files at the end of each test command and whenever
|
||
|
|
::tcltest::cleanupTests is called from all.tcl.
|
||
|
|
<P><DT><A NAME="M74">2</A><DD>
|
||
|
|
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.
|
||
|
|
<P></DL>
|
||
|
|
<P>
|
||
|
|
(::tcltest::preserveCore)
|
||
|
|
<P><DT><A NAME="M75"><B>-debug <debugLevel></B></A><DD>
|
||
|
|
print debug information to stdout. This is used to debug code in the
|
||
|
|
test harness. The default debug level is 0. Levels are defined as:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M76">0</A><DD>
|
||
|
|
Do not display any debug information.
|
||
|
|
<P><DT><A NAME="M77">1</A><DD>
|
||
|
|
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).
|
||
|
|
<P><DT><A NAME="M78">2</A><DD>
|
||
|
|
Display the flag array parsed by the command line processor, the
|
||
|
|
contents of the ::env array, and all user-defined variables that exist
|
||
|
|
in the current namespace as they are used.
|
||
|
|
<P><DT><A NAME="M79">3</A><DD>
|
||
|
|
Display information regarding what individual procs in the test
|
||
|
|
harness are doing.
|
||
|
|
<P></DL>
|
||
|
|
<P>
|
||
|
|
(::tcltest::debug)
|
||
|
|
<P><DT><A NAME="M80"><B>-outfile <filename></B></A><DD>
|
||
|
|
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::outputChannel)
|
||
|
|
<P><DT><A NAME="M81"><B>-errfile <filename></B></A><DD>
|
||
|
|
print errors generated by the tcltest package to the named file. This
|
||
|
|
defaults to stderr. (::tcltest::errorChannel)
|
||
|
|
<P></DL>
|
||
|
|
<P>
|
||
|
|
A second way to run tets is to start up a shell, load the
|
||
|
|
<B>tcltest</B> 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.
|
||
|
|
<P>
|
||
|
|
See <I>"Test Constraints"</I> for all built-in constraint names
|
||
|
|
that can be used in the <B>::tcltest::testConstraints</B> array.
|
||
|
|
See <I>"Tcltest namespace variables"</I> for details on other variables
|
||
|
|
defined in the <B>tcltest</B> namespace.
|
||
|
|
<P>
|
||
|
|
A final way to run tests would be to specify which test files to run
|
||
|
|
within an <I>all.tcl</I> (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), determines which test
|
||
|
|
files to run, sources each of these files, calls
|
||
|
|
::tcltest::cleanupTests and then exits.
|
||
|
|
<P>
|
||
|
|
A more elaborate <I>all.tcl</I> 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.
|
||
|
|
<H3><A NAME="M82">TEST OUTPUT</A></H3>
|
||
|
|
After all specified test files are run, the number of tests
|
||
|
|
passed, skipped, and failed is printed to
|
||
|
|
<B>::tcltest::outputChannel</B>. Aside from this
|
||
|
|
statistical information, output can be controlled on a per-test basis
|
||
|
|
by the <B>::tcltest::verbose</B> variable.
|
||
|
|
<P>
|
||
|
|
<B>::tcltest::verbose</B> can be set to any substring or permutation
|
||
|
|
of "bps". In the string "bps", the 'b' stands for a test's "body",
|
||
|
|
the 'p' stands for "passed" tests, and the 's' stands for "skipped"
|
||
|
|
tests. The default value of <B>::tcltest::verbose</B> 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,
|
||
|
|
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
|
||
|
|
the consraints that cause the test to be skipped) is printed for each
|
||
|
|
skipped test, otherwise no line is printed for skipped tests.
|
||
|
|
<P>
|
||
|
|
You can set <B>::tcltest::verbose</B> either interactively (after the
|
||
|
|
<B>tcltest</B> package has been loaded) or by using the command line
|
||
|
|
argument <B>-verbose</B>, for example:
|
||
|
|
<PRE>tclsh socket.test -verbose bps</PRE>
|
||
|
|
<H3><A NAME="M83">CONTENTS OF A TEST FILE</A></H3>
|
||
|
|
Test files should begin by loading the <B>tcltest</B> package:
|
||
|
|
<PRE>if {[lsearch [namespace children] ::tcltest] == -1} {
|
||
|
|
package require tcltest
|
||
|
|
namespace import ::tcltest::*
|
||
|
|
}</PRE>
|
||
|
|
Test files should end by cleaning up after themselves and calling
|
||
|
|
<B>::tcltest::cleanupTests</B>. The <B>::tcltest::cleanupTests</B>
|
||
|
|
procedure prints statistics about the number of tests that passed,
|
||
|
|
skipped, and failed, and removes all files that were created using the
|
||
|
|
<B>::tcltest::makeFile</B> and <B>::tcltest::makeDirectory</B> procedures.
|
||
|
|
<PRE># Remove files created by these tests
|
||
|
|
# Change to original working directory
|
||
|
|
# Unset global arrays
|
||
|
|
::tcltest::cleanupTests
|
||
|
|
return</PRE>
|
||
|
|
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.
|
||
|
|
For example, the test file for the C file "tclCmdAH.c" is "cmdAH.test".
|
||
|
|
Test files that contain black-box tests should match the pattern "*_bb.test".
|
||
|
|
<H3><A NAME="M84">SELECTING TESTS FOR EXECUTION WITHIN A FILE</A></H3>
|
||
|
|
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:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT>[1]<DD>
|
||
|
|
the <I>name</I> of the tests does not match (using glob style matching)
|
||
|
|
one or more elements in the <B>::tcltest::match</B> variable
|
||
|
|
<P><DT>[2]<DD>
|
||
|
|
the <I>name</I> of the tests matches (using glob style matching) one or
|
||
|
|
more elements in the <B>::tcltest::skip</B> variable
|
||
|
|
<P><DT>[3]<DD>
|
||
|
|
the <I>constraints</I> argument to the <B>::tcltest::test</B> call, if
|
||
|
|
given, contains one or more false elements.
|
||
|
|
<P></DL>
|
||
|
|
<P>
|
||
|
|
You can set <B>::tcltest::match</B> and/or <B>::tcltest::skip</B>
|
||
|
|
either interactively (after the <B>tcltest</B> package has been
|
||
|
|
sourced), or by using the command line arguments <B>-match</B> and
|
||
|
|
<B>-skip</B>, for example:
|
||
|
|
<P>
|
||
|
|
<PRE>tclsh info.test -match '*-5.* *-7.*' -skip '*-7.1*'</PRE>
|
||
|
|
<P>
|
||
|
|
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.
|
||
|
|
<P>
|
||
|
|
Predefined constraints (e.g. <I>knownBug</I> and <I>nonPortable</I>) can be
|
||
|
|
overridden either interactively (after the <B>tcltest</B> package has been
|
||
|
|
sourced) by setting the proper
|
||
|
|
<B>::tcltest::testConstraints(</B><I>constraint</I><B>)</B> variable
|
||
|
|
or by using the <B>-constraints</B> 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 <I>knownBug</I> and <I>nonPortable</I>
|
||
|
|
restrictions:
|
||
|
|
<P>
|
||
|
|
<PRE>tclsh all.tcl -constraints "knownBug nonPortable"</PRE>
|
||
|
|
<P>
|
||
|
|
See the <I>"Constraints"</I> package for information about using
|
||
|
|
built-in constraints and adding new ones.
|
||
|
|
<H3><A NAME="M85">HOW TO CUSTOMIZE THE TEST HARNESS</A></H3>
|
||
|
|
To create your own custom test harness, create a .tcl file that contains your
|
||
|
|
namespace. Within this file, require package <B>tcltest</B>. Commands
|
||
|
|
that can be redefined to customize the test harness include:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M86"><B>::tcltest::PrintUsageInfoHook</B></A><DD>
|
||
|
|
print additional usage information specific to your situation.
|
||
|
|
<P><DT><A NAME="M87"><B>::tcltest::processCmdLineArgsFlagHook</B></A><DD>
|
||
|
|
tell the test harness about additional flags that you want it to understand.
|
||
|
|
<P><DT><A NAME="M88"><B>::tcltest::processCmdLineArgsHook</B> <I>flags</I></A><DD>
|
||
|
|
process the additional flags that you told the harness about in
|
||
|
|
::tcltest::processCmdLineArgsFlagHook.
|
||
|
|
<P><DT><A NAME="M89"><B>::tcltest::initConstraintsHook</B></A><DD>
|
||
|
|
used to add additional built-in constraints to those already defined
|
||
|
|
by <B>tcltest</B>.
|
||
|
|
<P><DT><A NAME="M90"><B>::tcltest::cleanupTestsHook</B></A><DD>
|
||
|
|
do additional cleanup
|
||
|
|
<P></DL>
|
||
|
|
<P>
|
||
|
|
<P>
|
||
|
|
To add new flags to your customized test harness, redefine
|
||
|
|
<B>::tcltest::processCmdLineArgsAddFlagHook</B> to define additional flags to be
|
||
|
|
parsed and <B>::tcltest::processCmdLineArgsHook</B> to actually process them.
|
||
|
|
For example:
|
||
|
|
<PRE>proc ::tcltest::processCmdLineArgsAddFlagHook {} {
|
||
|
|
return [list -flag1 -flag2]
|
||
|
|
}
|
||
|
|
|
||
|
|
proc ::tcltest::processCmdLineArgsHook {flagArray} {
|
||
|
|
array set flag $flagArray
|
||
|
|
|
||
|
|
if {[info exists flag(-flag1)]} {
|
||
|
|
# Handle flag1
|
||
|
|
}
|
||
|
|
|
||
|
|
if {[info exists flag(-flag2)]} {
|
||
|
|
# Handle flag2
|
||
|
|
}
|
||
|
|
|
||
|
|
return
|
||
|
|
}</PRE>
|
||
|
|
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
|
||
|
|
::tcltest::PrintUsageInfoHook proc. Within this proc, you should
|
||
|
|
print out additional usage information for any flags that you've
|
||
|
|
implemented.
|
||
|
|
<P>
|
||
|
|
To add new built-in
|
||
|
|
constraints to the test harness, define your own version of
|
||
|
|
<B>::tcltest::initConstraintsHook</B>.
|
||
|
|
Within your proc, you can add to the <B>::tcltest::testConstraints</B> array.
|
||
|
|
For example:
|
||
|
|
<PRE>proc ::tcltest::initConstraintsHook {} {
|
||
|
|
set ::tcltest::testConstraints(win95Or98) \
|
||
|
|
[expr {$::tcltest::testConstraints(95) || \
|
||
|
|
$::tcltest::testConstraints(98)}]
|
||
|
|
}</PRE>
|
||
|
|
<P>
|
||
|
|
Finally, if you want to add additional cleanup code to your harness
|
||
|
|
you can define your own <B>::tcltest::cleanupTestsHook</B>. For example:
|
||
|
|
<PRE>proc ::tcltest::cleanupTestsHook {} {
|
||
|
|
# Add your cleanup code here
|
||
|
|
}</PRE>
|
||
|
|
<H3><A NAME="M91">EXAMPLES</A></H3>
|
||
|
|
<DL>
|
||
|
|
<P><DT>[1]<DD>
|
||
|
|
A simple test file (foo.test)
|
||
|
|
<PRE>if {[lsearch [namespace children] ::tcltest] == -1} {
|
||
|
|
package require tcltest
|
||
|
|
namespace import ::tcltest::*
|
||
|
|
}
|
||
|
|
|
||
|
|
test foo-1.1 {save 1 in variable name foo} {} {
|
||
|
|
set foo 1
|
||
|
|
} {1}
|
||
|
|
|
||
|
|
::tcltest::cleanupTests
|
||
|
|
return</PRE>
|
||
|
|
<P><DT>[2]<DD>
|
||
|
|
A simple all.tcl
|
||
|
|
<PRE>if {[lsearch [namespace children] ::tcltest] == -1} {
|
||
|
|
package require tcltest
|
||
|
|
namespace import ::tcltest::*
|
||
|
|
}
|
||
|
|
|
||
|
|
set ::tcltest::testSingleFile false
|
||
|
|
set ::tcltest::testsDirectory [file dir [info script]]
|
||
|
|
|
||
|
|
foreach file [::tcltest::getMatchingTestFiles] {
|
||
|
|
if {[catch {source $file} msg]} {
|
||
|
|
puts stdout $msg
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
::tclttest::cleanupTests 1
|
||
|
|
return</PRE>
|
||
|
|
<P><DT>[3]<DD>
|
||
|
|
Running a single test
|
||
|
|
<PRE>tclsh foo.test</PRE>
|
||
|
|
<P><DT>[4]<DD>
|
||
|
|
Running multiple tests
|
||
|
|
<PRE>tclsh all.tcl -file 'foo*.test' -notfile 'foo2.test'</PRE>
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M92">KEYWORDS</A></H3>
|
||
|
|
<A href="../Keywords/T.htm#test">test</A>, <A href="../Keywords/T.htm#test harness">test harness</A>, <A href="../Keywords/T.htm#test suite">test suite</A>
|
||
|
|
<HR><PRE>
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1990-1994 The Regents of the University of California
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1998-1999 Scriptics Corporation
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||
|
|
</BODY></HTML>
|