20060303-partial

1 files changed, 124 insertions, 0 deletions

diff --git a/man/1/itest b/man/1/itest
new file mode 100644
index 00000000..28eb7c15
--- /dev/null
+++ b/man/1/itest
@@ -0,0 +1,124 @@
+.TH ITEST 1
+.SH NAME
+itest, itreplay \- run tests and replay results
+.SH SYNOPSIS
+.B itest
+[
+.I -eo
+]
+[
+.I -c cflag
+]
+[
+.I -r count
+]
+[
+.I -v vlevel
+]
+[
+.I -C configfile
+]
+[
+.I -R recordroot
+]
+[
+.I testdir ...
+]
+.PP
+.B itreplay
+[
+.I -eo
+]
+[
+.I -v verbosity
+]
+[
+.I recorddir ...
+]
+.SH DESCRIPTION
+.I Itest
+runs a sequence of tests, optionally recording all the results in
+a directory tree. The
+.IR itreplay
+command replays the results of one or more recorded tests.
+Some options are common to both commands:
+.TP
+.B -e
+Display the standard error produced by the tests.
+.TP
+.B -o
+Display the standard output produced by the tests.
+.TP
+.BI -v " vlevel"
+Set the verbosity level to
+.I vlevel
+(0-9). The higher the value, the more detail is displayed; the default level is 3.
+.PP
+The tests run by
+.IR itest
+are specified as one or more directories either on the command line or in a configuration file. Options:
+.TP
+.BI -c " cflag"
+Set the value in /dev/jit (usually 0 or 1; 0 for interpreted mode, 1 for compiled mode) to
+.I cflag
+.TP
+.BI -r " count"
+Run the set of tests 
+.I count
+times; a value of 0 means repeat indefinitely.
+.TP
+.BI -v " vlevel"
+Set the verbosity level to
+.I vlevel
+(0-9). The higher the value, the more detail is displayed; the default level is 3.
+.TP
+.BI -C " cfile"
+Use the configuration file
+.I cfile.
+The file should contain a list of test directories, one per line.
+.TP
+.BI -R " recroot"
+Store the test results in a tree rooted at 
+.I recroot.
+Record directories are named as integers starting at 1. Each test run creates a new
+directory numbered one greater than the highest existing directory.
+.PP
+The test results to be replayed by
+.IR itreplay
+are specified on the command line as one or more record directories.
+.SS TEST FORMAT
+A test directory must contain either a t.dis file or a t.sh file, depending
+on whether the test is written as a Limbo program or as a
+.IR sh (1)
+script. Limbo programs should use 
+.IR itslib (2);
+sh scripts should use
+.IR sh-test (2).
+A test directory should also contain a README file (which is displayed by
+.I itest
+if the verbosity level is greater than 8), and any other files required
+for the test.
+.PP
+Tests are run with their working directory set to their own test directory.
+.SS RECORD DIRECTORY FORMAT
+Each record directory contains a number of files:
+.TP
+.BI msgs
+All the messages generated by the test.
+.TP
+.BI stderr
+Standard error from the test.
+.TP
+.BI stdout
+Standard output from the test.
+.TP
+.BI summary
+a one-line file containing the start time in seconds, elapsed time in ms, cflag
+and the name of the test directory.
+.SH SOURCE
+.B /appl/cmd/itest.b
+.br
+.B /appl/cmd/itreplay.b
+.SH SEE ALSO
+.IR itslib (2),
+.IR sh-test (2)