ATRN provider

[exim.git] / test / README

diff --git a/test/README b/test/README
index c0f548292adf422a8ecaa47a4e239324e44f398d..1798c4dc20831be1d49a32256c83a70d4a91349b 100644 (file)
--- a/test/README
+++ b/test/README
@@ -132,6 +132,9 @@ In order to run this test suite, the following requirements must be met:
      assumes the simpler I/O model.
      Exim must *not* be built with HEADERS_CHARSET set to UTF-8.
 
+(11) If building any dynamically-loaded lookups, LOOKUP_MODULE_DIR should
+     be set to .../exim/test/eximdir.
+
 
 
 OPTIONAL EXTRAS
@@ -301,6 +304,11 @@ There are some options for the ./runtest script itself:
   -SLOW     For very slow hosts that appear to have Heisenbugs, delay before
             comparing output files from a testcase
 
+  -TLS <client>  For cross-library testing. Specify 'openssl" or 'gnutls'
+            as the client; the other is used as the server (assumes that
+           both have been built: set up Local/Makefile for OpenSSL and
+           "make exim_openssl", then for GnuTLS and "make exim_gnutls")
+
 The options for ./runtest must be given first (but after the name of the
 binary, if present). Any further options, that is, items on the command line
 that start with a hyphen, are passed to the Exim binary when it is run as part
@@ -676,7 +684,12 @@ script. For example:
   # -bS Use of HELO/RSET
 
 A line consisting just of digits is interpreted as the expected return code
-for the command that follows. The default expectation when no such line exists
+for the command that follows.
+
+A line consisting of a tilde (~) followed by digits indicates a non-expected
+return code for the command that follows.
+
+The default expectation when neither such line exists
 is a zero return code. For example, here is a complete test script, containing
 just one command:
 
@@ -696,6 +709,17 @@ be replaced by the local host's name. Long commands can be continued over
 several lines by using \ as a continuation character. This does *not* apply to
 data lines.
 
+A line with a leading number followed by a space and then an uppercase
+word, equals character, value sets an expected return code as above
+plus an environment variable.  Example:
+
+  255 TZ=GB
+  exim_msgdate -l -u -z -localhost_number=20 000000 1PANS3 ZZZZZZ
+  ****
+
+
+
+
 Here follows a list of supported commands. They can be divided into two groups:
 
 
@@ -747,6 +771,12 @@ This command runs the exigrep utility with the given data (the search pattern)
 on the current mainlog file.
 
 
+  exiqgrep <data>
+
+This command runs the exiqgrep utility with the given options
+on the current spool directory.
+
+
   gnutls
 
 This command is present at the start of all but one of the tests that use
@@ -814,6 +844,14 @@ are still in existence at the end of the run (for messages that were not
 delivered) are not compared with saved versions.
 
 
+  no_munge
+
+If this command is encountered anywhere in the script, the output is not
+munged before it is compared with a saved version.
+This option allows meaningful tests of the exim_msgdate utility;
+without it all date comparison checks would succeed.
+
+
   no_stderr_check
 
 If this command is encountered anywhere in the script, the stderr output from
@@ -1047,6 +1085,7 @@ Lines in client scripts are of several kinds:
 (1) "??? ": If a line begins with three question marks and a space, the rest of the
     line defines the start of expected output from the server. If what is
     received does not match, the client bombs out with an error message.
+    Escape sequences described below in (7) are usable in the expected text.
 
 (2) "???*": If a line begins with three question marks and an asterisk, the server
     is expected to close the connection.
@@ -1119,13 +1158,16 @@ are of the following kinds:
 (2) A line that starts with "*sleep" specifies a number of seconds to wait
     before proceeding.
 
-(3) A line containing "*eof" specifies that the client is expected to close
+(3) A line containing "*data" and a number specifies that the client is
+    expected to send that many bytes; the server discards them
+
+(4) A line containing "*eof" specifies that the client is expected to close
     the connection at this point.
 
-(4) A line containing just '.' specifies that the client is expected to send
+(5) A line containing just '.' specifies that the client is expected to send
     many lines, terminated by one that contains just a dot.
 
-(5) Otherwise, the line defines the start of an input line that the client
+(6) Otherwise, the line defines the start of an input line that the client
     is expected to send. To allow for lines that start with digits, the line
     may start with '<', which is not taken as part of the input data. If the
     lines starts with '<<' then only the characters are expected; no return-
@@ -1170,7 +1212,7 @@ whose content is fixed, and those whose content needs to be varied according to
 the current environment. The former are kept in the directory aux-fixed. The
 latter are distributed in the directory aux-var-src, and copied with the
 standard substitutions into the directory aux-var at the start of each test
-run.
+run (with TESTNUM from the numeric prefix of the filename is there is one).
 
 Most of the auxiliary files have names that start with a test number,
 indicating that they are specific to that one test. A few fixed files (for