This is the TESH tool. It constitutes a testing shell, ie a sort of shell
specialized to run tests. The list of actions to take is parsed from files
files called testsuite. 

Testsuites syntax
-----------------
Here is the syntax of these files:

The kind of each line is given by the first char (the second char should be
blank and is ignored):
 
 `$' command to run in forground
 `&' command to run in background
 `<' input to pass to the command
 `>' output expected from the command
 `!' metacommand, which can be one of:
     `timeout' <integer>|no
     `expect signal' <signal name>
     `expect return' <integer>
     `output' <ignore|display>
     `setenv <key>=<val>'
 `p' a string to print
 `P' a string to print at the CRITICAL level (ease logging grepping)

If the expected output do not match what the command spits, TESH will produce
an error showing the diff (see OUTPUT below).

Command line arguments
----------------------
Tesh accepts several command line arguments:
  --cd some/directory: ask tesh to switch the working directory before
                       lauching the tests
  --setenv var=value: set a specific environment variable		       

IO orders
---------

The < and > lines add IO to the command defined in the current block (blocks
are separated by blank lines). It is possible to place these lines either after
the command or before. The difference between the two following chunks is
mainly cosmetic in your testsuites, TESH don't care. (cf IO-orders.tesh)

 $ cat
 < TOTO
 > TOTO

 > TOTO
 $ cat
 < TOTO

Nevertheless, it is possible to have several commands in the same block, but
none of them can have any output. It may seem a bit restrictive, as one could
say that a command gets all the IO until the next command, but I'm afraid of
errors such as the following:

 $ cd toto
 > TOTO
 $ mkfile file

TOTO will be passed to the cd command, where the user clearly want to pass it
to the mkfile buildin command (see below).

Stream redirection
------------------
Stream redirections (">", "<" and "|" constructs in sh) are not
implemented yet in tesh. This is a bit restrictive, but well, patch
welcome...

The situation in which it is mainly problematic is to create a
temporary file. The solution is to use the "mkfile" buildin command,
as in the following example:
$ mkfile myFile
> some content
> to the file

This will create a file called myFile (first argument of the mkfile
command). Its content will be all the input provided to the command.

RETURN CODE
-----------

TESH spits an appropriate error message when the child do not return 0 as
return code (cf. catch-return.tesh), and returns code+40 itself.

It is also possible to specify that a given command must return another
value. For this, use the "expect return" metacommand, which takes an integer as
argument. The change only apply to the next command (cf. set-return.tesh).

SIGNALS
-------

TESH detects when the child is killed by a signal (like on segfaults), and
spits an appropriate error message (cf. catch-signal.tesh).

It is also possible to specify that a given command must raise a given
signal. For this, use the "expect signal" metacommand. It takes the signal name
as argument. The change only apply to the next command (cf. set-signal.tesh).
 
TIMEOUTS
--------

By default, all commands are given 5 seconds to execute
(cf. catch-timeout.tesh). You can change this with the "timeout", which
takes an integer as argument. The change only apply to the next command
(cf. set-timeout.tesh). If you pass "no" as argument, the command
cannot timeout.

OUTPUT
------

By default, the commands output is matched against the one expected,
and an error is raised on discrepency. Metacomands to change this:
 "output ignore"  -> output completely discarded 
 "output display" -> output displayed (but not verified)
 "output sort"    -> sorts the display before verifying it (see below)

SORTING OUTPUT
--------------
Sorting the output seems to be a strange idea, but it is mandatory in
SimGrid since the processes run out of order at any scheduling point
(ie, every processes ready to run at simulated time t run in
parallel). To ensure that the simulator outputs still match, we have
to sort the output back before comparing it. 

We expect the simulators to run with that log formating argument:
   -log=root.fmt:[%10.6r]%e(%i:%P@%h)%e%m%n
Then, tesh sorts string on the 19 first chars only, and is stable when
line beginings are equal. This should ensure that:
 (1) tesh is effective (no false positive, no false negative)
 (2) scheduling points are separated from each other 
 (3) at each scheduling point, processes are separated from each other 
 (4) the order of what a given process says at a given scheduling
     point is preserved.
     
This is of course very SimGrid oriented, breaking the generality of
tesh, but who cares, actually?     

If you want to change the length of the prefix used for the sort,
simply specify it after the output sort directive, like this:

! output sort 22
 
ENVIRONMENT
-----------
You can add some content to the tested processes environment with the
setenv metacommand. It works as expected. For example:
  "setenv PATH=/bin"