Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Reindent everything (possibly breaking all branches, but for the last time)
[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 IO orders
29 ---------
30
31 The < and > lines add IO to the command defined in the current block (blocks
32 are separated by blank lines). It is possible to place these lines either after
33 the command or before. The difference between the two following chunks is
34 mainly cosmetic in your testsuites, TESH don't care. (cf IO-orders.tesh)
35
36  $ cat
37  < TOTO
38  > TOTO
39
40  > TOTO
41  $ cat
42  < TOTO
43
44 Nevertheless, it is possible to have several commands in the same block, but
45 none of them can have any output. It may seem a bit restrictive, as one could
46 say that a command gets all the IO until the next command, but I'm afraid of
47 errors such as the following:
48
49  $ cd toto
50  > TOTO
51  $ mkfile file
52
53 TOTO will be passed to the cd command, where the user clearly want to pass it
54 to the mkfile buildin command (see below).
55
56 Stream redirection
57 ------------------
58 Stream redirections (">", "<" and "|" constructs in sh) are not
59 implemented yet in tesh. This is a bit restrictive, but well, patch
60 welcome...
61
62 The situation in which it is mainly problematic is to create a
63 temporary file. The solution is to use the "mkfile" buildin command,
64 as in the following example:
65 $ mkfile myFile
66 > some content
67 > to the file
68
69 This will create a file called myFile (first argument of the mkfile
70 command). Its content will be all the input provided to the command.
71
72 RETURN CODE
73 -----------
74
75 TESH spits an appropriate error message when the child do not return 0 as
76 return code (cf. catch-return.tesh), and returns code+40 itself.
77
78 It is also possible to specify that a given command must return another
79 value. For this, use the "expect return" metacommand, which takes an integer as
80 argument. The change only apply to the next command (cf. set-return.tesh).
81
82 SIGNALS
83 -------
84
85 TESH detects when the child is killed by a signal (like on segfaults), and
86 spits an appropriate error message (cf. catch-signal.tesh).
87
88 It is also possible to specify that a given command must raise a given
89 signal. For this, use the "expect signal" metacommand. It takes the signal name
90 as argument. The change only apply to the next command (cf. set-signal.tesh).
91  
92 TIMEOUTS
93 --------
94
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
101 OUTPUT
102 ------
103
104 By default, the commands output is matched against the one expected,
105 and an error is raised on discrepency. Metacomands to change this:
106  "output ignore"  -> output completely discarded 
107  "output display" -> output displayed (but not verified)
108  
109 ENVIRONMENT
110 -----------
111 You can add some content to the tested processes environment with the
112 setenv metacommand. It works as expected. For example:
113   "setenv PATH=/bin"