tools/tesh/README.tesh

   1 This is the TESH tool. It constitutes a testing shell, ie a sort of shell
   2 specialized to run tests. The list of actions to take is parsed from files
   3 files called testsuite.
   4
   5 Testsuites syntax
   6 -----------------
   7 Here is the syntax of these files:
   8
   9 The kind of each line is given by the first char (the second char should be
  10 blank and is ignored):
  11
  12  `$' command to run in forground
  13  `&' command to run in background
  14  `<' input to pass to the command
  15  `>' output expected from the command
  16  `!' metacommand, which can be one of:
  17      `set timeout' <integer>
  18      `expect signal' <signal name>
  19      `expect return' <integer>
  20
  21 If the expected output do not match what the command spits, TESH will produce
  22 an error showing the diff.
  23
  24 IO orders
  25 ---------
  26
  27 The < and > lines add IO to the command defined in the current block (blocks
  28 are separated by blank lines). It is possible to place these lines either after
  29 the command or before. The difference between the two following chunks is
  30 mainly cosmetic in your testsuites, TESH don't care. (cf IO-orders.tesh)
  31
  32  $ cat
  33  < TOTO
  34  > TOTO
  35
  36  > TOTO
  37  $ cat
  38  < TOTO
  39
  40 Nevertheless, it is possible to have several commands in the same block, but
  41 none of them can have any output. It may seem a bit restrictive, as one could
  42 say that a command gets all the IO until the next command, but I'm afraid of
  43 errors such as the following:
  44
  45  $ cd toto
  46  > TOTO
  47  $ cat > file
  48
  49 TOTO will be passed to the cd command, where the user clearly want to pass it
  50 to cat.
  51
  52 RETURN CODE
  53 -----------
  54
  55 TESH spits an appropriate error message when the child do not return 0 as
  56 return code (cf. catch-return.tesh).
  57
  58 It is also possible to specify that a given command must return another
  59 value. For this, use the "expect return" metacommand, which takes an integer as
  60 argument. The change only apply to the next command (cf. set-return.tesh).
  61
  62 SIGNALS
  63 -------
  64
  65 TESH detects when the child is killed by a signal (like on segfaults), and
  66 spits an appropriate error message (cf. catch-signal.tesh).
  67
  68 It is also possible to specify that a given command must raise a given
  69 signal. For this, use the "expect signal" metacommand. It takes the signal name
  70 as argument. The change only apply to the next command (cf. set-signal.tesh).
  71
  72 TIMEOUTS
  73 --------
  74
  75 By default, all commands are given 5 seconds to execute
  76 (cf. catch-timeout.tesh). You can change this with the "set timeout", which
  77 takes an integer as argument. The change only apply to the next command
  78 (cf. set-timeout.tesh).
  79