Logo AND Algorithmique Numérique Distribuée

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