monotone

monotone Mtn Source Tree

Root/tester.txt

1A testsuite is a lua script which defines commonly used globals for the
2individual tests, and lists those tests in the "tests" table. Each test is a
3directory containing a lua script named "__driver__.lua", and optionally any
4number of data files. These data files can be copied to the scratch directory
5with "get(filename)".
6
7Each test is run in a scratch directory, named tester_dir/$TESTNAME relative to
8the directory in which the tester is run. If the test passes and the -d option
9is not given, this directory will be removed after the test finishes. The tester
10will leave a logfile named "tester.log" in tester_dir and in each scratch dir
11that isn't removed.
12
13tester should be called as
14tester testsuite [-dlh] [num [...]] [num..num [...]] [regex [...]]
15
16 -h print a help message
17 -l print test names only; don't run them
18 -d don't clean the scratch directories
19 num run a specific test
20 num..num run tests in a range
21 if num is negative, count back from the end
22 regex run tests with matching names
23
24On startup, the testsuite file is run. It should set up any global vars that the
25tests need, and add them to the "tests" table, as 'table.insert(tests,
26"test-name")'. "test-name" is the name of the directory for this test relative
27to testdir, which is initialized to srcdir (where the testsuite file is).
28
29After this the internal run_tests function is called, which parses the
30command-line arguments and runs whichever tests have been asked for. It also
31resets most of the environment between tests.
32
33
34tests
35
36Global table, containing all tests. The testsuite should contain lines of
37 table.insert(tests, "test-name")
38.
39
40test.root
41
42The scratch directory.
43
44test.name
45
46The name of the test.
47
48test.wanted_fail
49
50Set when an xfailed command succeeds.
51
52test.partial_skip
53
54Set this if you want to note that part of a test is being skipped.
55
56test.log
57
58The logfile for this individual test.
59
60srcdir
61
62Set to the dir containing the testsuite.
63
64testdir
65
66The directory containing all test stuff. Initially set to srcdir. Where all
67testsuite-related files are in a subdir except for the testsuite itself, the
68testsuite should set this to that dir. For example, the monotone testsuite
69sets this to srcdir.."/tests" .
70
71debugging
72
73Set to true if the -d option was given.
74
75logfile
76
77The general log.
78
79failed_testlogs
80
81List of logfiles for failed tests, to be appended to the general log.
82
83files
84
85Table of files for built-in commands (grep, cat, sort, etc) to use for i/o.
86
87
88
89P(...)
90
91Print arguments (written to stdout and to the main logfile).
92
93L(...)
94
95Log arguments (written to the test logfile, which will be appended to the main
96logfile if this test fails).
97
98getsrcline()
99
100returns (test.name, sourceline), where sourceline is the line number of the
101oldest stack frame which is in the driver file for the current test
102
103locheader()
104
105Line getsrcline(), except that it returns a string suitable for prefixing log
106lines, as L(locheader(), message).
107
108err(what [, level])
109
110Cause the test to fail, by throwing an error. This is like error(), except
111that it records the getsrcline() of where the error was thrown.
112
113mtime(filename) [logged]
114
115Returns the file modification time.
116
117mkdir(filename) [logged]
118
119Create the specified directory.
120
121existsonpath(name) [logged]
122
123Returns true if "name" is on the path.
124
125numlines(filename) [logged]
126
127Count the lines in a file.
128
129open_or_err()
130
131Wrapper around io.open, that throws instead of returning an error code.
132
133fsize(filename)
134
135Return the size of the given file.
136
137readfile(filename) [logged]
138
139Return the contents of a file. The unlogged version is readfile_q.
140
141readstdfile(filename)
142
143Calls readfile(), taking filename as relative to the testsuite directory.
144
145writefile(filename [, dat]) [logged]
146
147If dat is given, set the file contents to dat. If dat is not given, only make
148sure that the file exists. The unlogged version is writefile_q.
149
150append(filename [, dat]) [logged]
151
152Append dat to the given file.
153
154copy(from, to) [logged]
155
156Copy a file or a directory tree. The unlogged version is unlogged_copy.
157
158rename(from, to) [logged]
159
160Like os.rename except that it removes the destination if it already exists
161(because os.rename on Windows will not replace an existing destination). The
162unlogged version is unlogged_rename.
163
164remove(filename) [logged]
165
166Remove a file or a directory tree. The unlogged version is unlogged_remove.
167
168getstd(name [, as])
169
170Copy a file or a directory tree named 'name' from the testsuite directory to
171the scratch directory, giving it the name 'as', or 'name' is as is not given.
172
173get(name [, as])
174
175Copy a file or a directory tree named 'name' from the test directory to
176the scratch directory, giving it the name 'as', or 'name' is as is not given.
177
178include(filename)
179
180Load and execute a file, named relative to the testsuite directory.
181
182trim(string)
183
184Return the string, with leading and trailing whitespace removed.
185
186execute(path, ...) [internal]
187
188Run an external program, and return the program's return code.
189
190runcmd(cmd, prefix, bgnd) [internal]
191
192Run cmd under i/o redirection. cmd is a table giving either a function and
193arguments, or an external program name and agruments.
194
195samefile(left, right)
196
197Return true if the given files have identical contents, or false otherwise.
198
199samelines(file, table)
200
201Split the file into lines, and check that each line matches the corresponding
202element of the table. This function doesn't care what the line endings are.
203
204greplines(file, table)
205
206Split the file into lines, and check that each line is matched by the regex
207given in the corresponding table element.
208
209grep(["-qv"], "what" [, "filename"])
210cat(...)
211tail(file, num)
212sort([filename])
213
214These functions each return a table, suitable for passing to pcall() or check().
215They are meant to be used in place of the shell utilities of the same names.
216
217log_file_contents(filename)
218
219Write the contents of the given file to the test log.
220
221pre_cmd() [internal]
222
223Set up the files used for i/o redirection of commands.
224
225post_cmd() [internal]
226
227Verify that a command gave the expected results, and throw an error if it
228did not.
229
230bg(torun, ret, stdout, stderr, stdin)
231
232Run a command in the background. The arguments are:
233torunlist of strings, {"program", "arg1", "arg2" ,...}
234retexpected return code
235std{out,err}
236falseignore output
237truesave the output in a file named stdout or stderr
238stringthe string must match the output
239{string} the named file must match the output
240nil (not given)the output must be empty
241stdin
242trueuse existing "stdin" file
243nil, falseempty input
244stringcontents of string are used as input
245{string} contents of named file are used as input
246The returned object has two methods:
247finish(timeout)
248wait for the given timeout, then kill the program and check
249the results. Returns true.
250wait(timeout)
251wait for the given timeout. If the program has ended, check
252the results and return true. Otherwise, return false.
253
254runcheck() [internal]
255
256check(), minus some of the input validation
257
258indir(dir, cmd)
259
260cmd is a command table, as would be passed to check(). This wraps what it would
261do with a chdir() pair to run it in the given directory.
262
263check(first, ...)
264
265Run a command, and verify the results:
266check(torun, ret, stdout, stderr, stdin)
267Inputs are the same as to bg().
268check(bool)
269Throw an error if the argument is false.
270check(number)
271Check that the argument is zero.
272If the command fails, abort the test.
273
274skip_if(bool)
275
276If the argument is true, abort the test (throw true) and mark it as skipped.
277
278xfail(...)
279
280Equivalent to xfail_if(true, ...).
281
282xfail_if(chk, ...)
283
284Give the ... arguments to check(), and catch any errors. If chk is false just
285rethrow anything caught, so this wrapper is transparent. If chk is true, then
286either mark the test for unexpected success (if the command succeeded), or
287abort and mark it as an expected failure (throw false).
288
289log_error() [internal]
290
291Write a caught error to the test log.
292
293run_tests() [internal]
294
295Parse command line arguments, load the testsuite, and run specified tests.
296
297
298regex.search()
299globish.match()
300parse_basic_io()
301
302These functions are the same as in monotone.
303
304
305go_to_test_dir() [internal]
306set_redirect() [internal]
307clear_redirect() [internal]
308clean_test_dir() [internal]
309leave_test_dir() [internal]
310save_env() [internal]
311restore_env() [internal]
312
313Misc. infrastructure.
314
315get_source_dir()
316
317Return the directory the testsuite file was in.
318
319chdir()
320
321Go to a directory. You probably want to use indir() instead.
322
323exists()
324isdir()
325
326File status checks.
327
328get_ostype
329
330Return a string representing the OS. You probably care mostly about the
331first word.
332
333set_env()
334
335Set an environment variable.
336
337posix_umask
338
339Set the umask on posix systems, do nothing on Windows. If a test uses this, it
340should have a relevant skip_if.
341
342initial_dir
343
344Global variable, set to the directory the test program was started in.
345
346
347
348

Archive Download this file

Branches

Tags

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status