Logo AND Algorithmique Numérique Distribuée

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