1 files changed, 87 insertions, 4 deletions
diff --git a/tcl/tests/README b/tcl/tests/README
index 66a428ec6b6..4c88826f9ee 100644
--- a/tcl/tests/README
+++ b/tcl/tests/README
@@ -1,7 +1,90 @@
-README -- Tk test suite design document.
+README -- Tcl test suite design document.
 
 RCS: @(#) $Id$
 
-This directory contains a set of validation tests for the Tk commands.
-Please see the tests/README file in the Tcl source distribution for
-information about the test suite.
+Contents:
+---------
+
+    1. Introduction
+    2. Incompatibilities with prior Tcl versions
+
+1. Introduction:
+----------------
+
+This directory contains a set of validation tests for the Tcl commands
+and C Library procedures for Tcl.  Each of the files whose name ends
+in ".test" is intended to fully exercise the functions in the C source
+file that corresponds to the file prefix.  The C functions and/or Tcl
+commands tested by a given file are listed in the first line of the
+file.
+
+You can run the tests in three ways:
+
+    (a) type "make test" in ../unix; this will create the tcltest
+	executable and run all of the tests.  At least "make tcltest"
+	must be run to create the tcltest executable for the other
+	options.
+
+    (b) type "tcltest <testFile> ?<option> <value>?
+
+	where the options and values are the configuration options
+	of the tcltest package.
+ 
+    (c) start up tcltest in this directory, then "source" the test
+        file (for example, type "source parse.test").  To run all
+	of the tests, type "source all.tcl".  To use the options in
+	interactive mode, you can set them with the tcltest::configure
+	command.  Set constraints with the tcltest::testConstraints
+	command.
+
+Please see the tcltest man page for more information regarding how to
+write and run tests.
+
+Please note that the all.tcl file will source your new test file if
+the filename matches the tests/*.test pattern (as it should).  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 may not
+correspond to any Tcl or C code file so they should match the pattern
+"*_bb.test". 
+
+Be sure your new test file can be run from any working directory.
+
+Be sure no temporary files are left behind by your test file.
+Use [tcltest::makeFile], [tcltest::removeFile], and [tcltest::cleanupTests]
+properly to be sure of this.
+
+Be sure your tests can run cross-platform in both a build environment
+as well as an installation environment.  If your test file contains
+tests that should not be run in one or more of those cases, please use
+the constraints mechanism to skip those tests.
+
+2. Incompatibilities of package tcltest 2.1 with 
+   testing machinery of very old versions of Tcl:
+------------------------------------------------
+
+1) Global variables such as VERBOSE, TESTS, and testConfig of the
+   old machinery correspond to the [configure -verbose], 
+   [configure -match], and [testConstraint] commands of tcltest 2.1,
+   respectively.
+
+2) VERBOSE values were longer numeric.  [configure -verbose] values
+   are lists of keywords.
+
+3) When you run "make test", the working dir for the test suite is now
+   the one from which you called "make test", rather than the "tests"
+   directory.  This change allows for both unix and windows test
+   suites to be run simultaneously without interference with each
+   other or with existing files.  All tests must now run independently
+   of their working directory.
+
+4) The "all" file is now called "all.tcl"
+
+5) The "defs" and "defs.tcl" files no longer exist.
+
+6) Instead of creating a doAllTests file in the tests directory, to
+   run all nonPortable tests, just use the "-constraints nonPortable"
+   command line flag.  If you are running interactively, you can run
+   [tcltest::testConstraint nonPortable 1] (after loading the tcltest
+   package).