+++ /dev/null
-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"
\ No newline at end of file
