Tcl/Java Test Suite
--------------

RCS: @(#) $Id: README,v 1.3 2002/01/15 23:04:33 mdejong Exp $

This directory contains a set of validation tests for Tcl/Java.
Each of the files whose name ends in ".test" is intended to
fully exercise one or a few Tcl commands.  The commands tested
by a given file are listed in the first line of the file.

You can run the tests in two ways:
    (a) type "make test" in the build directory; this will run all of the tests.
    (b) type "make shell" in the build directory; cd to the test directory,
        then "source" the test file (for example, type "source parse.test").
        To run all of the tests, type "source all.tcl".
In either case no output will be generated if all goes well, except
for a listing of the tests. If there are errors then additional
messages will appear in the format described below. Note: don't
run the tests as superuser, since this will cause several of the tests
to fail.

The rest of this file provides additional information on the
features of the testing environment.

This approach to testing was designed and initially implemented
by Mary Ann May-Pumphrey of Sun Microsystems.  Many thanks to
her for donating her work back to the public Tcl release.

Definitions file:
-----------------

The file "defs" defines a collection of procedures and variables
used to run the tests. It is read in automatically by each of the
.test files if needed, but once it has been read once it will not
be read again by the .test files. If you change defs while running
tests you'll have to "source" it by hand to load its new contents.

Test output:
------------

Normally, output only appears when there are errors. However, if
the variable VERBOSE is set to 1 then tests will be run in "verbose"
mode and output will be generated for each test regardless of
whether it succeeded or failed. Test output consists of the
following information:

    - the test identifier (which can be used to locate the test code
	    in the .test file)
    - a brief description of the test
    - the contents of the test code
    - the actual results produced by the tests
    - a "PASSED" or "FAILED" message
    - the expected results (if the test failed)

You can set VERBOSE either interactively (after the defs file has been
read in), or you can change the default value in "defs".

Selecting tests for execution:
------------------------------

Normally, all the tests in a file are run whenever the file is
"source"d.  However, you can select a specific set of tests using
the global variable TESTS.  This variable contains a pattern;  any
test whose identifier matches TESTS will be run.  For example,
the following interactive command causes all of the "for" tests in
groups 2 and 4 to be executed:

    set TESTS {for-[24]*}

TESTS defaults to *, but you can change the default in "defs" if
you wish.

