sudo !tty_tickets; correct config file list.
[exim.git] / test / README
1 $Cambridge: exim/test/README,v 1.8 2007/02/20 15:58:02 ph10 Exp $
2
3 EXPORTABLE EXIM TEST SUITE
4 --------------------------
5
6 This document last updated for:
7
8 Test Suite Version: 4.67
9 Date: 20 February 2007
10
11
12 BACKGROUND
13 ----------
14
15 For a long time, the Exim test suite was confined to Philip Hazel's
16 workstation, because it relied on that particular environment. The problem is
17 that an MTA such as Exim interacts a great deal with its environment, so if you
18 run it somewhere else, the output will be different, which makes automatic
19 checking difficult. Even in a single environment, things are not all that easy.
20 For instance, if Exim delivers a message, the log line (which one would want to
21 compare) contains a timestamp and an Exim message id that will be different
22 each time. This issue is dealt with by a Perl script that munges the output by
23 recognizing changing sequences and replacing them with fixed values before
24 doing a comparison. Another problem with exporting the original test suite is
25 that it assumes a version of Exim with more or less every optional feature
26 enabled.
27
28 This README describes a new test suite that is intended to be exportable and to
29 run in a number of different environments. The tests themselves are in no
30 particular order; they accumulated over the years as Exim was extended and
31 modified. They vary greatly in size and complexity. Some were specifically
32 constructed to test new features; others were made to demonstrate that a bug
33 had been fixed.
34
35 A few of the original tests have had to be omitted from this more general
36 suite because differences in operating system behaviour make it impossible to
37 generalize them. An example is a test that uses a version of Exim that is
38 setuid to the Exim user rather than root, with the deliver_drop_privilege
39 option set. In Linux, such a binary is able to deliver a message as the caller
40 of Exim, because it can revert to the caller's uid. In FreeBSD this is not the
41 case.
42
43
44 REQUIREMENTS
45 ------------
46
47 In order to run this test suite, the following requirements must be met:
48
49 (1) You should run the tests on a matching version of Exim, because the suite
50     is continuously updated to test the latest features and bug fixes. The
51     version you test does not, however, have to be installed as the live
52     version. You can of course try the tests on any version of Exim, but some
53     may fail. In particular, the test suite will fall apart horrible with
54     versions of Exim prior to 4.54.
55
56 (2) You can use any non-root login to run the tests, but there must be access
57     via "sudo" to root from this login. Privilege is required to override
58     configuration change checks and for things like cleaning up spool files,
59     but on the other hand, the tests themselves need to call Exim from a
60     non-root process. The use of "sudo" is the easiest way to achieve all this.
61     The test script uses "sudo" to do a number of things as root, so it is best
62     if you set a sudo timeout so that you do not have to keep typing a
63     password. For example, if you put
64
65       Defaults timestamp_timeout=480
66
67     in /etc/sudoers, a password lasts for 8 hours (a working day). It is
68     not permitted to run the tests as the Exim user because the test suite
69     tracks the two users independently.  Using the same user would result
70     in false positives on some tests.
71
72     Further, some tests invoke sudo in an environment where there might not be
73     a TTY, so tickets should be global, not per-TTY.  Taking this all together
74     and assuming a user of "exim-build", you might have this in sudoers:
75
76       Defaults:exim-build     timestamp_timeout=480,!tty_tickets
77
78 (3) The login under which you run the tests must be in the exim group so that
79     it has access to logs, spool files, etc. The login should not be one of the
80     names "userx", "usery", "userz", or a few other simple ones such as "abcd"
81     and "xyz" and single letters that are used in the tests. The test suite
82     expects the login to have a gecos name; I think it will now run if the
83     gecos field is empty but there may be anomalies.
84
85 (4) The directory into which you unpack the test suite must be accessible by
86     the Exim user, so that code running as exim can access the files therein. A
87     world-readable directory is fine. However, there may be problems if the
88     path name of the directory is excessively long. This is because it
89     sometimes appears in log lines or debug output, and if it is truncated, it
90     is no longer recognized.
91
92 (5) Exim must be built with its user and group specified at build time, and
93     with certain minimum facilities, namely:
94
95       Routers:    accept, dnslookup, manualroute, redirect
96       Transports: appendfile, autoreply, pipe, smtp
97       Lookups:    lsearch
98
99     Most Exim binaries will have these included.
100
101 (6) A C compiler is needed to build some test programs, and the test script is
102     written in Perl, so you need that.
103
104 (7) Some of the tests run Exim as a daemon, and others use a testing server
105     (described below). These require TCP ports. In the configurations and
106     scripts, the ports are parameterized, but at present, fixed values are
107     written into the controlling script. These are ports 1224 to 1229. If these
108     ports are not available for use, some of the tests will fail.
109
110 (8) There is an underlying assumption that the host on which the tests are
111     being run has an IPv4 address (which the test script seeks out). If there
112     is also an IPv6 address, additional tests are run when the Exim binary
113     contains IPv6 support. There are checks in the scripts for a running IPv4
114     interface; when one is not found, some tests are skipped (with a warning
115     message).
116
117 (9) Exim must be built with TRUSTED_CONFIG_LIST support, so that the test
118     configs can be placed into it. DISABLE_D_OPTION must not be used. If
119     ALT_CONFIG_PREFIX is used, it must contain the directory of the test-suite.
120     WHITELIST_D_MACROS should contain:
121     
122      DIR:EXIM_PATH:AA:ACL:ACLRCPT:ACL_MAIL:ACL_PREDATA:ACL_RCPT:AFFIX:ALLOW:ARG1:ARG2:AUTHF:AUTHS:AUTH_ID_DOMAIN:BAD:BANNER:BB:BR:BRB:CERT:COM:COMMAND_USER:CONNECTCOND:CONTROL:CREQCIP:CREQMAC:CRL:CSS:D6:DATA:DCF:DDF:DEFAULTDWC:DELAY:DETAILS:DRATELIMIT:DYNAMIC_OPTION:ELI:ERROR_DETAILS:ERT:FAKE:FALLBACK:FILTER:FILTER_PREPEND_HOME:FORBID:FORBID_SMTP_CODE:FUSER:HAI:HAP:HARDLIMIT:HEADER_LINE_MAXSIZE:HEADER_MAXSIZE:HELO_MSG:HL:HOSTS:HOSTS_AVOID_TLS:HOSTS_MAX_TRY:HVH:IFACE:IGNORE_QUOTA:INC:INSERT:IP1:IP2:LAST:LDAPSERVERS:LENCHECK:LIMIT:LIST:LOG_SELECTOR:LS:MAXNM:MESSAGE_LOGS:MSIZE:NOTDAEMON:ONCE:ONLY:OPT:OPTION:ORDER:PAH:PEX:PORT:PTBC:QDG:QOLL:QUOTA:QUOTA_FILECOUNT:QWM:RCPT_MSG:REMEMBER:REQUIRE:RETRY:RETRY1:RETRY2:RETURN:RETURN_ERROR_DETAILS:REWRITE:ROUTE_DATA:RRATELIMIT:RT:S:SELECTOR:SELF:SERVER:SERVERS:SREQCIP:SREQMAC:SRV:STD:STRICT:SUB:SUBMISSION_OPTIONS:TIMEOUTDEFER:TIMES:TRUSTED:TRYCLEAR:UL:USE_SENDER:UTF8:VALUE:WMF:X:Y
123
124 (10) Exim must *not* be built with USE_READLINE, as the test-suite's automation
125      assumes the simpler I/O model.
126
127
128
129 OPTIONAL EXTRAS
130 ---------------
131
132 If the Exim binary that is being tested contains extra functionality in
133 addition to the minimum specified above, additional tests are run to exercise
134 the extra functionality, except for a few special cases such as the databases
135 (MySQL, PostgreSQL, LDAP) where special data is needed for the tests.
136
137
138 RUNNING THE TEST SUITE
139 ----------------------
140
141 (1) Download the tarball exim-testsuite-x.xx.tar.bz2 and unpack it, preferably
142     in a directory alongside an Exim source directory (see below).
143
144 (2) cd into the exim-testsuite-x.xx directory.
145
146 (3) Run "./configure" and then "make". This builds a few auxiliary programs
147     that are written in C.
148
149 (4) echo $PWD/test-config >> your_TRUSTED_CONFIG_LIST_filename
150
151 (5) Run "./runtest" (a Perl script) as described below.
152
153 (6) If you want to see what tests are available, run "./listtests".
154
155
156 BREAKING OUT OF THE TEST SCRIPT
157 -------------------------------
158
159 If you abandon the test run by typing ^C, the interrupt may be passed to a
160 program that the script is running, or it may be passed to the script itself.
161 In the former case, the script should detect that the program has ended
162 abnormally. In both cases, the script tries to clean up everything, including
163 killing any Exim daemons that it has started. However, there may be race
164 conditions in which the clean up does not happen. If, after breaking out of a
165 run, you see strange errors in the next run, look for any left-over Exim
166 daemons, and kill them by hand.
167
168
169 THE LISTTESTS SCRIPT
170 --------------------
171
172 The individual test scripts are in subdirectories of the "scripts" directory.
173 If you do not supply any arguments to ./listtests, it scans all the scripts in
174 all the directories, and outputs the heading line from each script. The output
175 is piped through "less", and begins like this:
176
177 === 0000-Basic ===
178 Basic/0001 Basic configuration setting
179 Basic/0002 Common string expansions
180 Basic/0003 Caseless address blocking
181 ...
182
183 Lines that start === give the name of the subdirectory containing the test
184 scripts that follow. If you supply an argument to ./listtests, it is used as a
185 Perl pattern to match case-independently against the names of the
186 subdirectories. Only those that match are scanned. For example, "./listtests
187 ipv6" outputs this:
188
189 === 1000-Basic-ipv6 ===
190 === Requires: support IPv6
191 Basic-ipv6/1000 -bh and non-canonical IPv6 addresses
192 Basic-ipv6/1001 recognizing IPv6 address in HELO/EHLO
193
194 === 2250-dnsdb-ipv6 ===
195 === Requires: support IPv6
196               lookup dnsdb
197 dnsdb-ipv6/2250 dnsdb ipv6 lookup in string expansions
198
199 If you supply a second argument to ./listtests, it is used as a Perl pattern to
200 match case-independently against the individual script titles. For example,
201 "./listtests . mx" lists all tests whose titles contain "mx", because "."
202 matches all the subdirectory names.
203
204
205 THE RUNTEST SCRIPT
206 ------------------
207
208 If you do not supply any arguments to ./runtest, it searches for an Exim
209 source tree at the same level as the test suite directory. It then looks for an
210 Exim binary in a "build" directory of that source tree. If there are several
211 Exim source trees, it chooses the latest version of Exim. Consider the
212 following example:
213
214   $ ls -F /source/exim
215   exim-4.60/  exim-4.62/  exim-testsuite-x.xx/
216
217 A simple ./runtest from within the test suite will use a 4.62 binary if it
218 finds one, otherwise a 4.60 binary. If a binary cannot be found, the script
219 prompts for one. Alternatively, you can supply the binary on the command line:
220
221   ./runtest /usr/exim/bin/exim
222
223 A matching test suite is released with each Exim release; if you use a test
224 suite that does not match the binary, some tests may fail.
225
226 The test suite uses some of the Exim utilities (such as exim_dbmbuild), and it
227 expects to find them in the same directory as Exim itself. If they are not
228 found, the tests that use them are omitted. A suitable comment is output.
229
230 On the ./runtest command line, following the name of the binary, if present,
231 there may be a number of options and then one or two numbers. The full syntax
232 is as follows:
233
234   ./runtest [binary name] [runtest options] [exim options] \
235             [first test] [last test]
236
237 There are some options for the ./runtest script itself:
238
239   -DEBUG    This option is for debugging the test script. It causes some
240             tracing information to be output.
241
242   -DIFF     By default, file comparisons are done using a private compare
243             command called "cf", which is built from source that is provided in
244             the src directory. This is a command I've had for nearly 20 years -
245             look at the source comments for its history - whose output I
246             prefer. However, if you want to use "diff" instead, give -DIFF as a
247             runtest option. In that case, "diff -u" is used for comparisons.
248             (If it turns out that most people prefer to use diff, I'll change
249             the default.)
250
251   -KEEP     Normally, after a successful run, the test output files are
252             deleted. This option prevents this. It is useful when running a
253             single test, in order to look at the actual output before it is
254             modified for comparison with saved output.
255
256   -NOIPV4   Pretend that an IPv4 interface was not found. This is useful for
257             testing that the test suite correctly skips tests that require
258             a running IPv4 interface.
259
260   -NOIPV6   Pretend that an IPv6 interface was not found. This is useful for
261             testing that the test suite correctly skips tests that require
262             a running IPv6 interface.
263
264   -UPDATE   If this option is set, any detected changes in test output are
265             automatically accepted and used to update the stored copies of the
266             output. It is a dangerous option, but it useful for the test suite
267             maintainer after making a change to the code that affects a lot of
268             tests (for example, the wording of a message).
269
270 The options for ./runtest must be given first (but after the name of the
271 binary, if present). Any further options, that is, items on the command line
272 that start with a hyphen, are passed to the Exim binary when it is run as part
273 of a test. The only sensible use of this is to pass "-d" in order to run a test
274 with debugging enabled. Any other options are likely to conflict with options
275 that are set in the tests. Some tests are already set up to run with debugging.
276 In these cases, -d on the command line overrides their own debug settings.
277
278 The final two arguments specify the range of tests to be run. Test numbers lie
279 in the range 1 to 9999. If no numbers are given, the defaults are 1 and 8999
280 (sic). Tests with higher numbers (9000 upwards) are not run automatically
281 because they require specific data (such as a particular MySQL table) that is
282 unlikely to be generally available.
283
284 Tests that require certain optional features of Exim are grouped by number, so
285 in any given range, not all the tests will exist. Non-existent tests are just
286 skipped, but if there are no tests at all in the given range, a message is
287 output.
288
289 If you give only one number, just that test is run (if it exists). Instead of a
290 second number, you can give the character "+", which is interpreted as "to the
291 end". Normally this is 8999; if the starting number is 9000 or higher, "+" is
292 interpreted as 9999. Examples:
293
294   ./runtest 1300
295   ./runtest 1400 1699
296   ./runtest /usr/sbin/exim 5000 +
297   ./runtest -DIFF -d 81
298
299 When the script starts up, the first thing it does is to check that you have
300 sudo access to root. Then it outputs the version number of the Exim binary that
301 it is testing, and also information about the optional facilities that are
302 present (obtained from "exim -bV"). This is followed by some environmental
303 information, including the current login id and the hosts's IP address. The
304 script checks that the current user is in the Exim group, and that the Exim
305 user has access to the test suite directory.
306
307 The script outputs the list of tests requested, and a list of tests that will
308 be omitted because the relevant optional facilities are not in the binary. You
309 are then invited to press Return to start the tests running.
310
311
312 TEST OUTPUT
313 -----------
314
315 When all goes well, the only permanent output is the identity of the tests as
316 they are run, and "Script completed" for each test script, for example:
317
318   Basic/0001 Basic configuration setting
319     Script completed
320   Basic/0002 Basic string expansions
321     Script completed
322   Basic/0003 Caseless address blocking
323     Script completed
324   Basic/0004 Caseful address blocking
325     Script completed
326   Basic/0005 -bs to simple local delivery
327   ...
328
329 While a script is running, it shows "Test n" on the screen, for each of the
330 Exim tests within the script. There may also be comments from some tests when a
331 delay is expected, for example, if there is a "sleep" while testing a timeout.
332
333 Before each set of optional tests, an extra identifying line is output. For
334 example:
335
336   >>> The following tests require: authenticator cram_md5
337   CRAM-MD5/2500 CRAM-MD5 server tests
338     Script completed
339   CRAM-MD5/2501 CRAM-MD5 client tests
340     Script completed
341
342 If a test fails, you are shown the output of the text comparison that failed,
343 and prompted as to what to do next. The output is shown using the "less"
344 command, or "more" if "less" is not available. The options for "less" are set
345 to that it automatically exits if there is less that a screenful of output. By
346 default, the output is from the "cf" program, and might look like this:
347
348   DBM/1300 DBM files and exim_dbmbuild
349   ===============
350   Lines 7-9 of "test-stdout-munged" do not match lines 7-11 of "stdout/1300".
351   ----------
352   exim_dbmbuild exit code = 1
353   Continued set of lines is too long: max permitted length is 99999
354   exim_dbmbuild exit code = 1
355   ----------
356   dbmbuild abandoned
357   exim_dbmbuild exit code = 2
358   Continued set of lines is too long: max permitted length is 99999
359   dbmbuild abandoned
360   exim_dbmbuild exit code = 2
361   ===============
362   1 difference found.
363   "test-stdout-munged" contains 16 lines; "stdout/1300" contains 18 lines.
364
365   Continue, Update & retry, Quit? [Q]
366
367 This example was generated by running the test with a version of Exim
368 that had a bug in the exim_dbmbuild utility (the bug was fixed at release
369 4.53). See "How the tests work" below for a description of the files that are
370 used. In this case, the standard output differed from what was expected.
371
372 The reply to the prompt must either be empty, in which case it takes the
373 default that is given in brackets (in this case Q), or a single letter, in
374 upper or lower case (in this case, one of C, U, or Q). If you type anything
375 else, the prompt is repeated.
376
377 "Continue" carries on as if the files had matched; that is, it ignores the
378 mismatch. Any other output files for the same test will be compared before
379 moving on to the next test.
380
381 "Update & retry" copies the new file to the saved file, and reruns the test
382 after doing any further comparisons that may be necessary.
383
384 Other circumstances give rise to other prompts. If a test generates output for
385 which there is no saved data, the prompt (after a message stating which file is
386 unexpectely not empty) is:
387
388   Continue, Show, or Quit? [Q]
389
390 "Show" displays the data on the screen, and then you get the "Continue..."
391 prompt. If a test ends with an unexpected return code, the prompt is:
392
393   show stdErr, show stdOut, Continue (without file comparison), or Quit? [Q]
394
395 Typically in these cases there will be something interesting in the stderr
396 or stdout output. There is a similar prompt after the "server" auxiliary
397 program fails.
398
399
400 OPENSSL AND GNUTLS ERROR MESSAGES
401 ---------------------------------
402
403 Some of the TLS tests deliberately cause errors to check how Exim handles them.
404 It has been observed that different releases of the OpenSSL and GnuTLS
405 libraries generate different error messages. This may cause the comparison with
406 the saved output to fail. Such errors can be ignored.
407
408
409 OTHER ISSUES
410 ------------
411
412 . Some of the tests are time-sensitive (e.g. when testing timeouts, as in test
413   461). These may fail if run on a host that is also running a lot of other
414   processes.
415
416 . Some versions of "ls" use a different format for times and dates. This can
417   cause test 345 to fail.
418
419 . Test 0142 tests open file descriptors; on some hosts the output may vary.
420
421
422 OTHER SCRIPTS AND PROGRAMS
423 --------------------------
424
425 There is a freestanding Perl script called "listtests" that scans the test
426 scripts and outputs a list of all the tests, with a short descriptive comment
427 for each one. Special requirements for groups of tests are also noted.
428
429 The main runtest script makes use of a second Perl script and some compiled C
430 programs. These are:
431
432 patchexim          A Perl script that makes a patched version of Exim (see the
433                    next section for details).
434
435 bin/cf             A text comparison program (see above).
436
437 bin/checkaccess    A program that is run as root; it changes uid/gid to the
438                    Exim user and group, and then checks that it can access
439                    files in the test suite's directory.
440
441 bin/client         A script-driven SMTP client simulation.
442
443 bin/client-gnutls  A script-driven SMTP client simulation with GnuTLS support.
444                    This is built only if GnuTLS support is detected on the host.
445
446 bin/client-ssl     A script-driven SMTP client simulation with OpenSSL support.
447                    This is built only if OpenSSL support is detected on the
448                    host.
449
450 bin/fakens         A fake "nameserver" for DNS tests (see below for details).
451
452 bin/fd             A program that outputs details of open file descriptors.
453
454 bin/iefbr14        A program that does nothing, and returns 0. It's just like
455                    the "true" command, but it is in a known place.
456
457 bin/loaded         Some dynamically loaded functions for testing dlfunc support.
458
459 bin/mtpscript      A script-driven SMTP/LMTP server simulation, on std{in,out}.
460
461 bin/server         A script-driven SMTP server simulation, over a socket.
462
463 bin/showids        Output the current uid, gid, euid, egid.
464
465 The runtest script also makes use of a number of ordinary commands such as
466 "cp", "kill", "more", and "rm", via the system() call. In some cases these are
467 run as root by means of sudo.
468
469
470 STANDARD SUBSTITUTIONS
471 ----------------------
472
473 In the following sections, there are several references to the "standard
474 substitutions". These make changes to some of the stored files when they are
475 used in a test. To save repetition, the substitutions themselves are documented
476 here:
477
478   CALLER         is replaced by the login name of the user running the tests
479   CALLERGROUP    is replaced by the caller's group id
480   CALLER_GID     is replaced by the caller's group id
481   CALLER_UID     is replaced by the caller's user id
482   DIR            is replaced by the name of the test-suite directory
483   EXIMGROUP      is replaced by the name of the Exim group
484   EXIMUSER       is replaced by the name of the Exim user
485   HOSTIPV4       is replaced by the local host's IPv4 address
486   HOSTIPV6       is replaced by the local host's IPv6 address
487   HOSTNAME       is replaced by the local host's name
488   PORT_D         is replaced by a port number for normal daemon use
489   PORT_N         is replaced by a port number that should never respond
490   PORT_S         is replaced by a port number for normal bin/server use
491   TESTNUM        is replaced by the current test number
492   V4NET          is replaced by an IPv4 network number for testing
493   V6NET          is replaced by an IPv6 network number for testing
494
495 PORT_D is currently hard-wired to 1225, PORT_N to 1223, and PORT_S to 1224.
496 V4NET is hardwired to 224 and V6NET to ff00. These networks are used for DNS
497 testing purposes, and for testing Exim with -bh. The only requirement is that
498 they are networks that can never be used for an IP address of a real host. I've
499 chosen two multicast networks for the moment.
500
501 If the host has no IPv6 address, "<no IPv6 address found>" is substituted but
502 that does not matter because no IPv6 tests will be run. A similar substitution
503 is made if there is no IPv4 address, and again, tests that actually require a
504 running IPv4 interface should be skipped.
505
506 If the host has more than one IPv4 or IPv6 address, the first one that
507 "ifconfig" lists is used. If the only available address is 127.0.0.1 (or ::1
508 for IPv6) it is used, but another value is preferred if available.
509
510 In situations where a specific test is not being run (for example, when setting
511 up dynamic data files), TESTNUM is replaced by an empty string, but should not
512 in fact occur in such files.
513
514
515 HOW THE TESTS WORK
516 ------------------
517
518 Each numbered script runs Exim (sometimes several times) with its own Exim
519 configuration file. The configurations are stored in the "confs" directory,
520 and before running each test, a copy of the appropriate configuration, with the
521 standard substitutions, is made in the file test-config. The -C command line
522 option is used to tell Exim to use this configuration.
523
524 The -D option is used to pass the path of the Exim binary to the configuration.
525 This is not standardly substituted, because there are two possible binaries
526 that might be used in the same test (one setuid to root, the other to the exim
527 user). Some tests also make use of -D to vary the configuration for different
528 calls to the Exim binary.
529
530 Normally, of course, Exim gives up root privilege when -C and -D are used by
531 unprivileged users. We do not want this to happen when running the tests,
532 because we want to be able to test all aspects of Exim, including receiving
533 mail from unprivileged users. The way this is handled is as follows:
534
535 At the start of the runtest script, the patchexim script is run as root. This
536 script makes a copy of the Exim binary that is to be tested, patching it as it
537 does so. (This is a binary patch, not a source patch.) The patch causes the
538 binary, when run, to "know" that it is running in the test harness. It does not
539 give up root privilege when -C and -D are used, and in a few places it takes
540 other special actions, such as delaying when starting a subprocess to allow
541 debug output from the parent to be written first. If you want to know more,
542 grep the Exim source files for "running_in_test_harness".
543
544 The patched binary is placed in the directory eximdir/exim and given the normal
545 setuid root privilege. This is, of course, a dangerous binary to have lying
546 around, especially if there are unprivileged users on the system. To protect
547 it, the eximdir directory is created with the current user as owner, exim as
548 the group owner, and with access drwx--x---. Thus, only the user who is running
549 the tests (who is known to have access to root) and the exim user have access
550 to the modified Exim binary. When runtest terminates, the patched binary is
551 removed.
552
553 Each set of tests proceeds by interpreting its controlling script. The scripts
554 are in subdirectories of the "scripts" directory. They are split up according
555 to the requirements of the tests they contain, with the 0000-Basic directory
556 containing tests that can always be run. Run the "listtests" script to obtain a
557 list of tests.
558
559
560 TEST OUTPUT
561 -----------
562
563 Output from script runs is written to the files test-stdout and test-stderr.
564 When an Exim server is involved, test-stdout-server and test-stderr-server are
565 used for its output. Before being compared with the saved output, the
566 non-server and server files are concatenated, so a single saved file contains
567 both.
568
569 A directory called spool is used for Exim's spool files, and for Exim logs.
570 These locations are specified in every test's configuration file.
571
572 When messages are delivered to files, the files are put in the test-mail
573 directory. Output from comparisons is written to test-cf.
574
575 Before comparisons are done, output texts are modified ("munged") to change or
576 remove parts that are expected to vary from run to run. The modified files all
577 end with the suffix "-munged". Thus, you will see test-stdout-munged,
578 test-mainlog-munged, test-mail-munged, and so on. Other files whose names start
579 with "test-" are created and used by some of the tests.
580
581 At the end of a successful test run, the spool directory and all the files
582 whose names begin with "test-" are removed. If the run ends unsuccessfully
583 (typically after a "Q" response to a prompt), the spool and test files are left
584 in existence so that the problem can be investigated.
585
586
587 TEST COMMANDS
588 -------------
589
590 Each test script consists of a list of commands, each optionally preceded by
591 comments (lines starting with #) and (also optionally) a line containing an
592 expected return code. Some of the commands are followed by data lines
593 terminated by a line of four asterisks.
594
595 The first line of each script must be a comment that briefly describes the
596 script. For example:
597
598   # -bS Use of HELO/RSET
599
600 A line consisting just of digits is interpreted as the expected return code
601 for the command that follows. The default expectation when no such line exists
602 is a zero return code. For example, here is a complete test script, containing
603 just one command:
604
605   # -bS Unexpected EOF in headers
606   1
607   exim -bS -odi
608   mail from:<someone@some.where>
609   rcpt to:<blackhole@HOSTNAME>
610   data
611   from: me
612   ****
613
614 The expected return code in this case is 1, and the data lines are passed to
615 Exim on its standard input. Both the command line and the data lines have the
616 standard substitions applied to them. Thus, HOSTNAME in the example above will
617 be replaced by the local host's name. Long commands can be continued over
618 several lines by using \ as a continuation character. This does *not* apply to
619 data lines.
620
621 Here follows a list of supported commands. They can be divided into two groups:
622
623
624 Commands with no input
625 ----------------------
626
627 These commands are not followed by any input data, or by a line of asterisks.
628
629
630   dbmbuild <file1> <file1>
631
632 This command runs the exim_dbmbuild utility to build a DBM file. It is used
633 only when DBM support is available in Exim, and typically follows the use of a
634 "write" command (see below) that creates the input file.
635
636
637   dumpdb <dbname>
638
639 This command runs the exim_dumpdb utility on the testing spool directory, using
640 the database name given, for example: "dumpdb retry".
641
642
643   echo <text>
644
645 The text is written to the screen; this is used to output comments from
646 scripts.
647
648
649   exim_lock [options] <file name>
650
651 This command runs the exim_lock utility with the given options and file name.
652 The file remains locked with the following command (normally exim) is obeyed.
653
654
655   exinext <data>
656
657 This command runs the exinext utility with the given argument data.
658
659
660   exigrep <data>
661
662 This command runs the exigrep utility with the given data (the search pattern)
663 on the current mainlog file.
664
665
666   gnutls
667
668 This command is present at the start of all but one of the tests that use
669 GnuTLS. It copies a pre-existing parameter file into the spool directory, so
670 that Exim does not have to re-create the file each time. The first GnuTLS test
671 does not do this, in order to test that Exim can create the file.
672
673
674   killdaemon
675
676 This command must be given in any script that starts an Exim daemon, normally
677 at the end. It searches for the PID file in the spool directory, and sends a
678 SIGINT signal to the Exim daemon process whose PID it finds. See below for
679 comments about starting Exim daemons.
680
681
682   millisleep <m>
683
684 This command causes the script to sleep for m milliseconds. Nothing is output
685 to the screen.
686
687
688   need_ipv4
689
690 This command must be at the head of a script. If no IPv4 interface has been
691 found, the entire script is skipped, and a comment is output.
692
693
694   need_ipv6
695
696 This command must be at the head of a script. If no IPv6 interface has been
697 found, the entire script is skipped, and a comment is output.
698
699
700   need_largefiles
701
702 This command must be at the head of a script. If the Exim binary does not
703 suppport large files (off_t is <= 4), the entire script is skipped, and a
704 comment is output.
705
706
707   need_move_frozen_messages
708
709 This command must be at the head of a script. If the Exim binary does not have
710 support for moving frozen messages (which is an optional feature), the entire
711 script is skipped, and a comment is output.
712
713
714   no_message_check
715
716 If this command is encountered anywhere in the script, messages that are
717 delivered when the script runs are not compared with saved versions.
718
719
720   no_msglog_check
721
722 If this command is encountered anywhere in the script, message log files that
723 are still in existence at the end of the run (for messages that were not
724 delivered) are not compared with saved versions.
725
726
727   no_stderr_check
728
729 If this command is encountered anywhere in the script, the stderr output from
730 the run is not compared with a saved version.
731
732
733   no_stdout_check
734
735 If this command is encountered anywhere in the script, the stdout output from
736 the run is not compared with a saved version.
737
738
739   rmfiltertest
740
741 This command indicates that the script is for a certain type of filter test, in
742 which there are a lot of repetitive stdout lines that get in the way, because
743 filter tests output data about the sender and recipient. Such lines are removed
744 from the stdout output before comparing, for ease of human perusal.
745
746
747   sleep <n>
748
749 This command causes the script to sleep for n seconds. If n is greater than
750 one, "sleep <n>" is output to the screen, followed by a dot for every second
751 that passes.
752
753
754   sortlog
755
756 This command causes special sorting to occur on the mainlog file before
757 comparison. Every sequence of contiguous delivery lines (lines containing the
758 => -> or *> flags) is sorted. This is necessary in some tests that use parallel
759 deliveries because on different systems the processes may terminate in a
760 different order.
761
762
763 A number of standard file management commands are also recognized. These are
764 cat, chmod, chown, cp, du, ln, ls, du, mkdir, mkfifo, rm, rmdir, and touch.
765 Some are run as root using "sudo".
766
767
768 Commands with input
769 -------------------
770
771 The remaining commands are followed by data lines for their standard input,
772 terminated by four asterisks. Even if no data is required for the particular
773 usage, the asterisks must be given.
774
775
776   catwrite <file name> [nxm[=start-of-line-text]]*
777
778 This command operates like the "write" command, which is described below,
779 except that the data it generates is copied to the end of the test-stdout file
780 as well as to the named file.
781
782
783
784   client [<options>] <ip address> <port> [<outgoing interface>]
785
786 This command runs the auxiliary "client" program that simulates an SMTP client.
787 It is controlled by a script read from its standard input, details of which are
788 given below. There are two options. One is -t, which must be followed directly
789 by a number, to specify the command timeout in seconds (e.g. -t5). The default
790 timeout is 1 second. The other option is -tls-on-connect, which causes the
791 client to try to start up a TLS session as soon as it has connected, without
792 using the STARTTLS command. The client program connects to the given IP address
793 and port, using the specified interface, if one is given.
794
795
796   client-ssl [<options>] <ip address> <port> [<outgoing interface>] \
797              [<cert file>] [<key file>]
798
799 When OpenSSL is available on the host, an alternative version of the client
800 program is compiled, one that supports TLS using OpenSSL. The additional
801 arguments specify a certificate and key file when required. There is one
802 additional option, -tls-on-connect, that causes the client to initiate TLS
803 negotiation immediately on connection.
804
805
806   client-gnutls [<options>] <ip address> <port> [<outgoing interface>] \
807                 [<cert file>] [<key file>]
808
809 When GnuTLS is available on the host, an alternative version of the client
810 program is compiled, one that supports TLS using GnuTLS. The additional
811 arguments specify a certificate and key file when required. There is one
812 additional option, -tls-on-connect, that causes the client to initiate TLS
813 negotiation immediately on connection.
814
815
816   exim [<options>] [<arguments>]
817
818 This command runs the testing version of Exim. Any occurrence of "$msg1" in the
819 command line is replaced by the ID of the first (oldest) message in Exim's
820 (testing) spool. "$msg2" refers to the second, and so on. The name "exim" can
821 be preceded by an environment setting as in this example:
822
823   LDAPTLS_REQCERT=never exim -be
824
825 It can also be preceded by a number; this specifies a number of seconds to wait
826 before closing the stdout pipe to Exim, and is used for some timeout tests. For
827 example:
828
829   3 exim -bs
830
831 Finally, "exim" can be preceded by "sudo", to run Exim as root. If more than
832 one of these prefixes is present, they must be in the above order.
833
834
835   exim_exim [<options>] [<arguments>]
836
837 This runs an alternative version of Exim that is setuid to exim rather than to
838 root.
839
840
841   server [<options>] <port or socket> [<connection count>]
842
843 This command runs the auxiliary "server" program that simulates an SMTP (or
844 other) server. It is controlled by a script that is read from its standard
845 input, details of which are given below. A number of options are implemented:
846
847   -d       causes the server to output debugging information
848
849   -t       sets a timeout in seconds (default 5) for when the server is
850            awaiting an incoming connection
851
852   -noipv4  causes the server not to set up an IPv4 socket
853
854   -noipv6  causes the server not to set up an IPv6 socket
855
856 By default, in an IPv6 environment, both kinds of socket are set up. However,
857 the test script knows which interfaces actually exist on the host, and it adds
858 -noipv4 or -noipv6 to the server command as required. An error occurs if both
859 these options are given.
860
861 The only required argument is either a port number or the path name of a Unix
862 domain socket. The port is normally PORT_S, which is changed to an actual
863 number by the standard substitutions. The optional final argument specifies the
864 number of different connections to expect (default 1). These must happen
865 serially (one at a time). There is no support for multiple simultaneous
866 connections. Here are some example commands:
867
868   server PORT_S
869   server -t 10 PORT_S 3
870   server /tmp/somesocket
871
872 The following lines, up to a line of four asterisks, are the server's
873 controlling standard input (described below). These lines are read and
874 remembered; during the following commands, until an "exim" command is reached,
875 the server is run in parallel.
876
877
878   write <file name> [nxm[=start-of-line-text]]*
879
880 The "write" command is a way of creating files of specific sizes for buffering
881 tests, or containing specific data lines. Being able to do this from within the
882 script saves holding lots of little test files. The optional argument specifies
883 n lines of length m. The lines consist of the letter "a". If start of line text
884 is supplied, it replaces "a"s at the start of each line. Underscores in the
885 start of line text are turned into spaces. The optional argument may be
886 repeated. The data lines that follow a "write" command are split into two by a
887 line of four plus signs. Any above the split are written before the
888 fixed-length lines, and any below the split are written after. For example:
889
890   write test-data 3x30=AB_ 1x50
891   Pre-data
892   lines
893   ++++
894   Post-data
895   lines
896   ****
897
898 This command generates a file containing:
899
900   Pre-data
901   lines
902   AB aaaaaaaaaaaaaaaaaaaaaaaaaaa
903   AB aaaaaaaaaaaaaaaaaaaaaaaaaaa
904   AB aaaaaaaaaaaaaaaaaaaaaaaaaaa
905   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
906   Post-data
907   lines
908
909 If there are no fixed-length line specifiers, there is no need to split the
910 data, and a line of plusses is not needed.
911
912
913   [sudo] perl
914
915 This command runs Perl, with the data as its standard input, to allow arbitrary
916 one-off things to be done.
917
918
919 CLIENT SCRIPTS
920 --------------
921
922 Lines in client scripts are of two kinds:
923
924 (1) If a line begins with three question marks and a space, the rest of the
925     line defines the start of expected output from the server. If what is
926     received does not match, the client bombs out with an error message.
927
928 (2) If a line starts with three plus signs followed by a space, the rest of the
929     line specifies a number of seconds to sleep for before proceeding.
930
931 (3) Otherwise, the line is an input line line that is sent to the server. Any
932     occurrences of \r and \n in the line are turned into carriage return and
933     linefeed, respectively. This is used for testing PIPELINING.
934
935 Here is a simple example:
936
937   client 127.0.0.1 PORT_D
938   ??? 250
939   EHLO xxx
940   ??? 250-
941   ??? 250
942   AUTH PLAIN AbdXi0AdnD2CVy
943   ??? 535
944   quit
945   ??? 221
946   ****
947
948 In the case of client-gnutls and client-ssl, if a command is "starttls", this
949 is remembered, and after a subsequent OK response, an attempt to move into TLS
950 mode occurs. If a command is "starttls_wait", the client sends "starttls" but
951 does not start up TLS; this is for testing timeouts. If a command is "stoptls",
952 an existing TLS connection is shut down, but nothing is sent.
953
954
955 SERVER SCRIPTS
956 --------------
957
958 The server program sleeps till a connection occurs or its timeout is reached,
959 in which case it bombs out. The next set of command lines are interpreted. They
960 are of the following kinds:
961
962 (1) A line that starts with '>' or with a digit is an output line that is sent
963     to the client. In the case of '>':
964
965     (a) If the line starts with ">>", no terminating CRLF is sent.
966     (b) If the line starts with ">CR>", just CR is sent at the end.
967     (c) If the line starts with ">LF>", just LF is sent at the end.
968     (d) If the line starts with ">*eof", nothing is sent and the connection
969           is closed.
970
971     The data that is sent starts after the initial '>' sequence.
972
973 (2) A line that starts with "*sleep" specifies a number of seconds to wait
974     before proceeding.
975
976 (3) A line containing "*eof" specifies that the client is expected to close
977     the connection at this point.
978
979 (4) A line containing just '.' specifies that the client is expected to send
980     many lines, terminated by one that contains just a dot.
981
982 (5) Otherwise, the line defines the start of an input line that the client
983     is expected to send. To allow for lines that start with digits, the line
984     may start with '<', which is not taken as part of the input data. If the
985     input does not match, the server bombs out with an error message.
986
987 Here is a simple example of server use in a test script:
988
989   server PORT_S
990   220 Greetings
991   EHLO
992   250 Hello there
993   MAIL FROM
994   250 OK
995   RCPT TO
996   250 OK
997   DATA
998   354 Send it!
999   .
1000   250 OK
1001   QUIT
1002   225 OK
1003   ****
1004
1005 After a "server" command in a test script, the server runs in parallel until an
1006 "exim" command is reached. The "exim" command attempts to deliver one or more
1007 messages to port PORT_S on the local host. When it has finished, the test
1008 script waits for the "server" process to finish.
1009
1010 The "mtpscript" program is like "server", except that it uses stdin/stdout for
1011 its input and output instead of a script. However, it is not called from test
1012 scripts; instead it is used as the command for pipe transports in some
1013 configurations, to simulate non-socket LMTP servers.
1014
1015
1016 AUXILIARY DATA FILES
1017 --------------------
1018
1019 Many of the tests make use of auxiliary data files. There are two types; those
1020 whose content is fixed, and those whose content needs to be varied according to
1021 the current environment. The former are kept in the directory aux-fixed. The
1022 latter are distributed in the directory aux-var-src, and copied with the
1023 standard substitutions into the directory aux-var at the start of each test
1024 run.
1025
1026 Most of the auxiliary files have names that start with a test number,
1027 indicating that they are specific to that one test. A few fixed files (for
1028 example, some TLS certificates) are used by more than one test, and so their
1029 names are not of this form.
1030
1031 There are also some auxilary DNS zone files, which are described in the next
1032 section.
1033
1034
1035 DNS LOOKUPS AND GETHOSTBYNAME
1036 -----------------------------
1037
1038 The original test suite required special testing zones to be loaded into a
1039 local nameserver. This is no longer a requirement for the new suite. Instead, a
1040 program called fakens is used to simulate a nameserver. When Exim is running in
1041 the test harness, instead of calling res_search() - the normal call to the DNS
1042 resolver - it calls a testing function. This handles a few special names itself
1043 (for compatibility with the old test suite), but otherwise passes the query to
1044 the fakens program.
1045
1046 The fakens program consults "zone files" in the directory called dnszones, and
1047 returns data in the standard resource record format for Exim to process as if
1048 it came from the DNS. However, if the requested domain is not in any of the
1049 zones that fakens knows about, it returns a special code that causes Exim to
1050 pass the query on to res_search(). The zone files are:
1051
1052   db.test.ex    A zone for the domain test.ex.
1053   db.ip4.10     A zone for one special case in 10.250.0.0/16 (see below)
1054   db.ip4.V4NET  A zone for the domain V4NET.in-addr.arpa.
1055   db.ip4.127    A zone for the domain 127.in-addr.arpa.
1056   db.ip6.V6NET  A zone for the domain inverted(V6NET).ip6.arpa.
1057   db.ip6.0      A zone for the domain 0.ip6.arpa.
1058
1059 V4NET and V6NET are substituted with the current testing networks (see above).
1060 In the case of V6NET, the network is four hex digits, and it is split and
1061 inverted appropriately when setting up the zone.
1062
1063 These fake zone files are built dynamically from sources in the dnszones-src
1064 directory by applying the standard substitutions. The test suite also builds
1065 dynamic zone files for the name of the current host and its IP address(es). The
1066 idea is that there should not be any need to rely on an external DNS.
1067
1068 The domain names that are handled directly by Exim, without being passed to
1069 fakens, are:
1070
1071   test.again.dns    This always provokes a TRY_AGAIN response, for testing the
1072                     handling of temporary DNS error. If the full domain name
1073                     starts with digits, a delay of that many seconds occurs.
1074
1075   test.fail.dns     This always provokes a NO_RECOVERY response, for testing
1076                     DNS server failures.
1077
1078 This special handling could now be done in the fakens program, but while the
1079 old test suite is still being used it has to be done in Exim itself, so for the
1080 moment it remains there.
1081
1082 The use of gethostbyname() and its IPv6 friends is also subverted when Exim is
1083 running in the test harness. The test code handles a few special names
1084 directly; for all the others it uses DNS lookups, which are then handled as
1085 just described. Thus, the use of /etc/hosts is completely bypassed. The names
1086 that are specially handled are:
1087
1088   manyhome.test.ex  This name is used for testing hosts with ridiculously large
1089                     numbers of IP addresses; 2048 IP addresses are generated
1090                     and returned. Doing it this way saves having to make the
1091                     interface to fakens handle more records that can fit in the
1092                     data block. The addresses that are generated are in the
1093                     10.250.0.0/16 network.
1094
1095   localhost         Always returns 127.0.0.1 or ::1, for IPv4 and IPv6 lookups,
1096                     respectively.
1097
1098   <an IP address>   If the IP address is of the correct form for the lookup
1099                     type (IPv4 or IPv6), it is returned. Otherwise a panic-die
1100                     error occurs.
1101
1102 The reverse zone db.ip4.10 is provided just for the manyhome.test.ex case. It
1103 contains a single wildcard resource record. It also contains the line
1104
1105   PASS ON NOT FOUND
1106
1107 Whenever fakens finds this line in a zone file, it returns PASS_ON instead of
1108 HOST_NOT_FOUND. This causes Exim to pass the query to res_search().
1109
1110 ****