Documentation of server testing program stest

Randal E. Bryant
Sept. 29, 2011

The stest program is designed to automatically test the LSP-based
password cracking server.  It executes the server program and then
creates a set of synthetic worker and request clients that interact
with it.  There are many commandline options that allow users to
control how the system operates, in terms of the creation and killing
of both request and worker clients.

INVOKING

The program is typically located in the "official" subdirectory and is
designed to be executed from the same directory as the server code.
It is therefore invoked as follows:

   ../official/stest <commandline options>

OPERATION

Each test is controlled by a test sequence, specified by a sequence of
letters and digits.  Each letter designates an operation, and the
following digits, when present, control that operation.  Here are the
allowed operations.  In the following, both <len>, <id>, and <status>
are numbers:

    f <len>	Request cracking of valid password of length <len>

    x <len>	Request cracking of invalid password of length <len>

    w 		Start a new worker

    W           Kill one of the workers

    W <status>	Kill one of the workers having the specified status:
      		status 1: Kill a worker that has found the password
		status 2: Kill a worker that has not found the password

    k <id>	Kill request client <id>.
      		(Requests are numbered from 1 upward)
	    
Here are some example sequences:
     f4ww:     Crack valid password of length 4 using two workers

     x4wWw:    Attempt to crack an invalid password of length 4.
     	       The first worker is started and killed, and then a
     	       second worker is started

     f4x5wwk2: Request cracking a valid password of length 4, an
     	       invalid password of length 5, add two workers,
	       then kill the second request.


When the test sequence is not specified on the command line, stest
steps through a set of 15 test sequences as follows:

1.    f4w
2.    f4ww
3.    x4ww
4.    x3f4wwf4x4ww
5.    x3f4wwf4x4WWwwwww
6.    x4wf4wwWf4x4WWwwwww
7.    x5wf4wwk1f4x4
8.    x4wf5wwk2WWf4x4wwww
9.    f5wwx4Wx4Wk1wwf4f5f4wwx3k5WWwwx4
10.   wwW0f4
11.   W1f4ww
12.   W2x4ww
13.   wwWW1wW2wf4
14.   x5wwwwwwwwwwwwwwww
15.   wwWf5W1wx4W2x4W1k1wwf4f5f4wwx3k5W2Wwwx5wwwwwwwwwwwwwww

At the end of a sequence, stest waits until all requests have been
completed, or an overall timeout occurs.  It then determines whether
or not the correct values have been returned.  Each sequence is marked as a
success or a failure.  When all sequences have been completed, stest prints
"PASS" if all sequences were successful, and "FAIL" otherwise

COMMAND LINE OPTIONS

	-h         Print help message
	-v N       Set verbosity level (0-3).  The default is 1
	-V N       Set verbosity level (0-6) of the LSP clients
	-l logfile Redirect stderr for the server to the designated file.
	   	   This will capture all output generated by a logger, including
		   the provided lsp.Vlogf function.
        -t T       Set the overall timeout limit to T seconds.  The
	           default is 60
        -s SEQ     Use run script SEQ, rather than the predefined ones