tools/tesh/tesh.1

   1 .\" Manpage for tesh
   2 .TH tesh 1 "10 Oct 2012" "1.0" "tesh man page"
   3 .SH NAME
   4 tesh \- testing shell
   5 .SH SYNOPSIS
   6 .B tesh
   7 [\fIOPTION\fR]... [\fIFILE\fR]...
   8 .SH DESCRIPTION
   9 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.
  10 .SH OPTIONS
  11   --cd some/directory: ask tesh to switch the working directory before
  12                        launching the tests
  13   --setenv var=value: set a specific environment variable
  14 .SH TESH FILE SYNTAX
  15 Here is the syntax of these files:
  16
  17 The kind of each line is given by the first char (the second char should be
  18 blank and is ignored):
  19
  20  `$' command to run in foreground
  21  `&' command to run in background
  22  `<' input to pass to the command
  23  `>' output expected from the command
  24  `!' metacommand, which can be one of:
  25      `timeout' <integer>|no
  26      `expect signal' <signal name>
  27      `expect return' <integer>
  28      `output' <ignore|display>
  29      `setenv <key>=<val>'
  30  `p' a string to print
  31  `P' a string to print at the CRITICAL level (ease logging grepping)
  32
  33 If the expected output do not match what the command spits, TESH will produce
  34 an error showing the diff (see OUTPUT below).
  35 .SH IO ORDERS
  36 The < and > lines add IO to the command defined in the current block (blocks
  37 are separated by blank lines). It is possible to place these lines either after
  38 the command or before. The difference between the two following chunks is
  39 mainly cosmetic in your testsuites, TESH don't care. (cf IO-orders.tesh)
  40
  41  $ cat
  42  < TOTO
  43  > TOTO
  44
  45  > TOTO
  46  $ cat
  47  < TOTO
  48
  49 Nevertheless, it is possible to have several commands in the same block, but
  50 none of them can have any output. It may seem a bit restrictive, as one could
  51 say that a command gets all the IO until the next command, but I'm afraid of
  52 errors such as the following:
  53
  54  $ cd toto
  55  > TOTO
  56  $ mkfile file
  57
  58 TOTO will be passed to the cd command, where the user clearly want to pass it
  59 to the mkfile built-in command (see below).
  60 .SH STREAM REDIRECTION
  61 Stream redirections (">", "<" and "|" constructs in sh) are not
  62 implemented yet in tesh. This is a bit restrictive, but well, patch
  63 welcome...
  64
  65 The situation in which it is mainly problematic is to create a
  66 temporary file. The solution is to use the "mkfile" built-in command,
  67 as in the following example:
  68 $ mkfile myFile
  69 > some content
  70 > to the file
  71
  72 This will create a file called myFile (first argument of the mkfile
  73 command). Its content will be all the input provided to the command.
  74 .SH RETURN CODE
  75 TESH spits an appropriate error message when the child do not return 0 as
  76 return code (cf. catch-return.tesh), and returns code+40 itself.
  77
  78 It is also possible to specify that a given command must return another
  79 value. For this, use the "expect return" metacommand, which takes an integer as
  80 argument. The change only apply to the next command (cf. set-return.tesh).
  81 .SH SIGNALS
  82 TESH detects when the child is killed by a signal (like on segfaults), and
  83 spits an appropriate error message (cf. catch-signal.tesh).
  84
  85 It is also possible to specify that a given command must raise a given
  86 signal. For this, use the "expect signal" metacommand. It takes the signal name
  87 as argument. The change only apply to the next command (cf. set-signal.tesh).
  88 .SH TIMEOUTS
  89 By default, all commands are given 5 seconds to execute
  90 (cf. catch-timeout.tesh). You can change this with the "timeout", which
  91 takes an integer as argument. The change only apply to the next command
  92 (cf. set-timeout.tesh). If you pass "no" as argument, the command
  93 cannot timeout.
  94 .SH OUTPUT
  95 By default, the commands output is matched against the one expected,
  96 and an error is raised on discrepancy. Metacommands to change this:
  97  "output ignore"  -> output completely discarded
  98  "output display" -> output displayed (but not verified)
  99  "output sort"    -> sorts the display before verifying it (see below)
 100 .SH SORTING OUTPUT
 101 Sorting the output seems to be a strange idea, but it is mandatory in
 102 SimGrid since the processes run out of order at any scheduling point
 103 (ie, every processes ready to run at simulated time t run in
 104 parallel). To ensure that the simulator outputs still match, we have
 105 to sort the output back before comparing it.
 106
 107 We expect the simulators to run with that log formatting argument:
 108    -log=root.fmt:[%10.6r]%e(%i:%P@%h)%e%m%n
 109 Then, tesh sorts string on the 19 first chars only, and is stable when
 110 line beginnings are equal. This should ensure that:
 111  (1) tesh is effective (no false positive, no false negative)
 112  (2) scheduling points are separated from each other
 113  (3) at each scheduling point, processes are separated from each other
 114  (4) the order of what a given process says at a given scheduling
 115      point is preserved.
 116
 117 This is of course very SimGrid oriented, breaking the generality of
 118 tesh, but who cares, actually?
 119
 120 If you want to change the length of the prefix used for the sort,
 121 simply specify it after the output sort directive, like this:
 122
 123 ! output sort 22
 124 .SH ENVIRONMENT
 125 You can add some content to the tested processes environment with the
 126 setenv metacommand. It works as expected. For example:
 127   "setenv PATH=/bin"
 128 .SH BUGS
 129 No known bugs.