From 6a85698d6176e117198e061607fd77dcb2d081a2 Mon Sep 17 00:00:00 2001 From: paul bedaride Date: Wed, 10 Oct 2012 17:38:08 +0200 Subject: [PATCH] add tesh man --- tools/tesh/tesh.1 | 129 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 tools/tesh/tesh.1 diff --git a/tools/tesh/tesh.1 b/tools/tesh/tesh.1 new file mode 100644 index 0000000000..35a02caf50 --- /dev/null +++ b/tools/tesh/tesh.1 @@ -0,0 +1,129 @@ +.\" Manpage for tesh +.TH tesh 1 "10 Oct 2012" "1.0" "tesh man page" +.SH NAME +tesh \- testing shell +.SH SYNOPSIS +.B ls +[\fIOPTION\fR]... [\fIFILE\fR]... +.SH DESCRIPTION +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. +.SH OPTIONS + --cd some/directory: ask tesh to switch the working directory before + launching the tests + --setenv var=value: set a specific environment variable +.SH TESH FILE 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 foreground + `&' command to run in background + `<' input to pass to the command + `>' output expected from the command + `!' metacommand, which can be one of: + `timeout' |no + `expect signal' + `expect return' + `output' + `setenv =' + `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). +.SH 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 built-in command (see below). +.SH 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. +.SH 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). +.SH 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). +.SH 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. +.SH OUTPUT +By default, the commands output is matched against the one expected, +and an error is raised on discrepancy. Metacommands 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) +.SH 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 beginnings 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 +.SH ENVIRONMENT +You can add some content to the tested processes environment with the +setenv metacommand. It works as expected. For example: + "setenv PATH=/bin" +.SH BUGS +No known bugs. -- 2.20.1