Testing procedures                                             [CRC test suite]
------------------

Let $BENCH be the name of the directory in which the tests are stored.  Then:

	$BENCH^/sys^              official testing tools

	$BENCH^/base^             base testing of Stata built-ins
	$BENCH^/ado^              testing of Stata ado-files
	$BENCH^/unique^           machine-unique testing

	$BENCH^/^*                other test files.


Test drivers
------------

A test driver is $BENCH^/^<testdir>^/test.do^.
The outline is:

	^*^ comments saying what the testdir is about
	^more^
	^set more 1^
	^do^ <testscript>       /* comment */
	^do^ <testscript>       /* comment */
	.
	^do^ <testscript>       /* comment */

A test driver should be executable by changing to $BENCH^/^<testdir>, entering
Stata and typing "^do test^".

Test scripts
------------

A test script is $BENCH^/^<testdir>^/^<testscript>^.do^.
The outline is:

	^do prolog^ <testscript name>
	<stata code>

A test script should be executable by changing to $BENCH^/^<testdir>, entering
Stata and typing "^do^ <testscript>".



Testing tools
-------------

Test scripts may use testing tools, one of which is ^prolog.do^.

^prolog.do^ presents a header, clears memory, and sets Stata into the default
configuration that it would have right after entering.  Thus, individual 
test scripts may be "dirty."  See the ^prolog.do^ file to see what is reset.
Additional things may be reset in the future.  Nevertheless, test scripts
should attempt to clean up after themselves.

^prolog.do^ does NOT reset ^maxvar^ or ^maxobs^.  If your test script changes these
values, it is the test script's responsibility to change them back.

There are other ado-files helpful in testing.

The idea is that, at any time, the materials in the $BENCH^/sys^ directory 
could be copied to any $BENCH^/^<testdir> directory without causing problems.
Note that $BENCH^/^<testdir> may have its own, unique ado-files.  If such 
ado-files are necessary, consider documenting them and including them in 
the $BENCH^/sys^ directory.

On-line help is available for the following testing tools:

asserteq . . . . . . . . . . . . . . . . . . . . . . Fuzzy equality comparison
chkdp  . . . . . . . . . . . . . . . . . . . .  Check data set partition stats
chksumm  . . . . . . . . . . . . . . . . . Check results reported by summarize
jumble . . . . . . . . . . . . . . . . . . .  Put observations in random order
rcof . . . . . . . . . . . . . . . . . . . . . . . . . . . . Check return code
setfwid  . . . . . . . . . . . . . . . . . . . . . . . . .  Consume free width
typeof . . . . . . . . . . . . . . . . . . . Make assertion about storage type


Creating a new $BENCH^/^<testdir>
-------------------------------

Create the directory.  Copy all materials from $BENCH^/sys^ into the new 
directory.

Also see
--------

On-line:  ^help^ for ^asserteq^, ^chkdp^, ^chksumm^, ^jumble^, ^rcof^, ^setfwid^,
          ^typeof^