Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
kill the C version of tesh (now unused). RIP :(
[simgrid.git] / tools / tesh / tesh.1
1 .\" Manpage for tesh, the TEsting SHell.
2 .\" 
3 .\" To read it locally (when not installed): 
4 .\"   man ./tesh.1
5 .\"
6 .TH tesh 1 "10 Oct 2012" "1.0" "tesh man page"
7 .SH NAME
8 tesh \- testing shell
9 .SH SYNOPSIS
10 .B tesh
11 [\fIOPTION\fR]... [\fIFILE\fR]...
12 .SH DESCRIPTION
13 This is the TESH tool. It constitutes a testing shell, ie a sort of shell specialized to run tests. The list of actions to take is parsed from files files called testsuite.
14 .SH OPTIONS
15   --cd some/directory : ask tesh to switch the working directory before
16                         launching the tests
17   --setenv var=value  : set a specific environment variable
18   --cfg arg           : add parameter --cfg=arg to each command line
19   --enable-coverage   : ignore output lines starting with "profiling:"
20 .SH TESH FILE SYNTAX
21 Here is the syntax of these files:
22
23 The kind of each line is given by the first char (the second char should be
24 blank and is ignored):
25
26  `$' command to run in foreground
27  `&' command to run in background
28  `<' input to pass to the command
29  `>' output expected from the command
30  `!' metacommand, which can be one of:
31      `timeout' <integer>|no
32      `expect signal' <signal name>
33      `expect return' <integer>
34      `output' <ignore|display>
35      `setenv <key>=<val>'
36  `p' a string to print
37  `P' a string to print at the CRITICAL level (ease logging grepping)
38
39 If the expected output do not match what the command spits, TESH will produce
40 an error showing the diff (see OUTPUT below).
41 .SH IO ORDERS
42 The < and > lines add IO to the command defined in the current block (blocks
43 are separated by blank lines). It is possible to place these lines either after
44 the command or before. The difference between the two following chunks is
45 mainly cosmetic in your testsuites, TESH don't care. (cf IO-orders.tesh)
46
47  $ cat
48  < TOTO
49  > TOTO
50
51  > TOTO
52  $ cat
53  < TOTO
54
55 Nevertheless, it is possible to have several commands in the same block, but
56 none of them can have any output. It may seem a bit restrictive, as one could
57 say that a command gets all the IO until the next command, but I'm afraid of
58 errors such as the following:
59
60  $ cd toto
61  > TOTO
62  $ mkfile file
63
64 TOTO will be passed to the cd command, where the user clearly want to pass it
65 to the mkfile built-in command (see below).
66 .SH STREAM REDIRECTION
67 Stream redirections (">", "<" and "|" constructs in sh) are not
68 implemented yet in tesh. This is a bit restrictive, but well, patch
69 welcome...
70
71 The situation in which it is mainly problematic is to create a
72 temporary file. The solution is to use the "mkfile" built-in command,
73 as in the following example:
74 $ mkfile myFile
75 > some content
76 > to the file
77
78 This will create a file called myFile (first argument of the mkfile
79 command). Its content will be all the input provided to the command.
80 .SH RETURN CODE
81 TESH spits an appropriate error message when the child do not return 0 as
82 return code (cf. catch-return.tesh), and returns code+40 itself.
83
84 It is also possible to specify that a given command must return another
85 value. For this, use the "expect return" metacommand, which takes an integer as
86 argument. The change only apply to the next command (cf. set-return.tesh).
87 .SH SIGNALS
88 TESH detects when the child is killed by a signal (like on segfaults), and
89 spits an appropriate error message (cf. catch-signal.tesh).
90
91 It is also possible to specify that a given command must raise a given
92 signal. For this, use the "expect signal" metacommand. It takes the signal name
93 as argument. The change only apply to the next command (cf. set-signal.tesh).
94 .SH TIMEOUTS
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 .SH OUTPUT
101 By default, the commands output is matched against the one expected,
102 and an error is raised on discrepancy. Metacommands to change this:
103  "output ignore"  -> output completely discarded
104  "output display" -> output displayed (but not verified)
105  "output sort"    -> sorts the display before verifying it (see below)
106 .SH SORTING OUTPUT
107 Sorting the output seems to be a strange idea, but it is mandatory in
108 SimGrid since the processes run out of order at any scheduling point
109 (ie, every processes ready to run at simulated time t run in
110 parallel). To ensure that the simulator outputs still match, we have
111 to sort the output back before comparing it.
112
113 We expect the simulators to run with that log formatting argument:
114    --log=root.fmt:[%10.6r]%e(%i:%P@%h)%e%m%n
115 Then, tesh sorts string on the 19 first chars only, and is stable when
116 line beginnings are equal. This should ensure that:
117  (1) tesh is effective (no false positive, no false negative)
118  (2) scheduling points are separated from each other
119  (3) at each scheduling point, processes are separated from each other
120  (4) the order of what a given process says at a given scheduling
121      point is preserved.
122
123 This is of course very SimGrid oriented, breaking the generality of
124 tesh, but who cares, actually?
125
126 If you want to change the length of the prefix used for the sort,
127 simply specify it after the output sort directive, like this:
128
129 ! output sort 22
130 .SH ENVIRONMENT
131 You can add some content to the tested processes environment with the
132 setenv metacommand. It works as expected. For example:
133   "setenv PATH=/bin"
134 .SH BUGS
135 No known bugs.