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