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