tools/tesh/tesh.1

   1 .\" Manpage for tesh, the TEsting SHell.
   2 .\"
   3 .\" To read it locally (when not installed):
   4 .\"   man ./tesh.1
   5 .\"
   6 .TH tesh 1 "10 Oct 2012" "1.0" "tesh man page"
   7 .SH NAME
   8 tesh \- testing shell
   9 .SH SYNOPSIS
  10 .B tesh
  11 [\fIOPTION\fR]... [\fIFILE\fR]...
  12 .SH DESCRIPTION
  13 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.
  14 .SH OPTIONS
  15   --cd some/directory : ask tesh to switch the working directory before
  16                         launching the tests
  17   --setenv var=value  : set a specific environment variable
  18   --cfg arg           : add parameter --cfg=arg to each command line
  19   --enable-coverage   : ignore output lines starting with "profiling:"
  20 .SH TESH FILE SYNTAX
  21 Here is the syntax of these files:
  22
  23 The kind of each line is given by the first char (the second char should be
  24 blank and is ignored):
  25
  26  `$' command to run in foreground
  27  `&' command to run in background
  28  `<' input to pass to the command
  29  `>' output expected from the command
  30  `!' metacommand, which can be one of:
  31      `timeout' <integer>|no
  32      `expect signal' <signal name>
  33      `expect return' <integer>
  34      `output' <ignore|display>
  35      `setenv <key>=<val>'
  36  `p' a string to print
  37  `P' a string to print at the CRITICAL level (ease logging grepping)
  38
  39 If the expected output do not match what the command spits, TESH will produce
  40 an error showing the diff (see OUTPUT below).
  41 .SH IO ORDERS
  42 The < and > lines add IO to the command defined in the current block (blocks
  43 are separated by blank lines). It is possible to place these lines either after
  44 the command or before. The difference between the two following chunks is
  45 mainly cosmetic in your testsuites, TESH don't care. (cf IO-orders.tesh)
  46
  47  $ cat
  48  < TOTO
  49  > TOTO
  50
  51  > TOTO
  52  $ cat
  53  < TOTO
  54
  55 Nevertheless, it is possible to have several commands in the same block, but
  56 none of them can have any output. It may seem a bit restrictive, as one could
  57 say that a command gets all the IO until the next command, but I'm afraid of
  58 errors such as the following:
  59
  60  $ cd toto
  61  > TOTO
  62  $ mkfile file
  63
  64 TOTO will be passed to the cd command, where the user clearly want to pass it
  65 to the mkfile built-in command (see below).
  66 .SH STREAM REDIRECTION
  67 Stream redirections (">", "<" and "|" constructs in sh) are not
  68 implemented yet in tesh. This is a bit restrictive, but well, patch
  69 welcome...
  70
  71 The situation in which it is mainly problematic is to create a
  72 temporary file. The solution is to use the "mkfile" built-in command,
  73 as in the following example:
  74 $ mkfile myFile
  75 > some content
  76 > to the file
  77
  78 This will create a file called myFile (first argument of the mkfile
  79 command). Its content will be all the input provided to the command.
  80 .SH RETURN CODE
  81 TESH spits an appropriate error message when the child do not return 0 as
  82 return code (cf. catch-return.tesh), and returns code+40 itself.
  83
  84 It is also possible to specify that a given command must return another
  85 value. For this, use the "expect return" metacommand, which takes an integer as
  86 argument. The change only apply to the next command (cf. set-return.tesh).
  87 .SH SIGNALS
  88 TESH detects when the child is killed by a signal (like on segfaults), and
  89 spits an appropriate error message (cf. catch-signal.tesh).
  90
  91 It is also possible to specify that a given command must raise a given
  92 signal. For this, use the "expect signal" metacommand. It takes the signal name
  93 as argument. The change only apply to the next command (cf. set-signal.tesh).
  94 .SH TIMEOUTS
  95 By default, all commands are given 5 seconds to execute
  96 (cf. catch-timeout.tesh). You can change this with the "timeout", which
  97 takes an integer as argument. The change only apply to the next command
  98 (cf. set-timeout.tesh). If you pass "no" as argument, the command
  99 cannot timeout.
 100 .SH OUTPUT
 101 By default, the commands output is matched against the one expected,
 102 and an error is raised on discrepancy. Metacommands to change this:
 103  "output ignore"  -> output completely discarded
 104  "output display" -> output displayed (but not verified)
 105  "output sort"    -> sorts the display before verifying it (see below)
 106 .SH SORTING OUTPUT
 107
 108 SimGrid is designed to produce perfectly reproducible results, so its
 109 output can usualy be compared without any preprocessing. This is not
 110 true anymore when the user activates parallel execution: User
 111 processes are run in parallel at each timestamp, and the output is not
 112 reproducible anymore. Until you sort the lines.
 113
 114 If you ask for
 115 .B ! output sort
 116 then tesh will sort the whole lines. But it really complicates the
 117 analysis of the error detected: the logical order of the output is
 118 defeated by the lexicographical sort.
 119
 120 The solution is to ask for
 121 .B ! output sort 19
 122 instead to sort only on the prefix of the line. Indeed, we run our simulation
 123 tests with the flag:
 124   --log=root.fmt:[%10.6r]%e(%i:%P@%h)%e%m%n
 125
 126 Then, the previous command sorts  lines on the first 19 chars, that is
 127 exactly the length of the prefix indicating the timestamp and the
 128 process. That's exactly what we need:
 129  - Every timestamps remain separated, as it should;
 130  - In each timestamp, the output order of processes become
 131    reproducible: that's the lexicographical order of their name;
 132  - For each process, the order of its execution is preserved: its
 133    messages within a given timestamp are not reordered.
 134
 135 That way, tesh can do its job (no false positive, no false negative)
 136 despite the unpredictable order of executions of processes within a
 137 timestamp, and reported errors remain easy to analyze (execution of a
 138 given process preserved).
 139
 140 This is of course very SimGrid oriented, but could even be usable by
 141 others, who knows?
 142
 143 .SH ENVIRONMENT
 144 You can add some content to the tested processes environment with the
 145 setenv metacommand. It works as expected. For example:
 146   "setenv PATH=/bin"
 147 .SH BUGS
 148 No known bugs.