`<' input to pass to the command
`>' output expected from the command
`!' metacommand, which can be one of:
- `set timeout' <integer>
+ `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.
+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
---------
$ cd toto
> TOTO
- $ cat > file
+ $ mkfile file
TOTO will be passed to the cd command, where the user clearly want to pass it
-to cat.
+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).
+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
--------
By default, all commands are given 5 seconds to execute
-(cf. catch-timeout.tesh). You can change this with the "set timeout", which
+(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).
-
+(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 20 first lines 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?
+
+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
