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