tools/tesh2/examples/README.tesh

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