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