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