Running the regression tests
----------------------------

The Makefile used for building can also be used to run a series of
regression tests that check for proper operation of individual
components of SpamAssassin. The tests should be run after building
SpamAssassin and before installing it. For example, a typical install
that includes the testing step would look like

 perl Makefile.PL
 make
 make test
 su
 make install

See the INSTALL file for details on the build and installation
process.

Regression Test Options
-----------------------

The test case scripts are located in directory t/ under the root
build directory, in files named t/*.t .

When the tests are run, those that are not applicable in your OS or
with the build options that you selected will be skipped.

Running a subset of the tests
------------------------------

To run some of the tests, specify TEST_FILES as in the following
example:

 make test TEST_FILES="t/spamc.t t/spamc_l.t"

Wildcards can be used in shell file globbing syntax, as in

 make test TEST_FILES="t/spam*.t"

The wildcard syntax does not work with standard Windows command
shells.

You can also run individual test scripts directly, from the "t" directory,
like so (note that it uses hardcoded #!/usr/bin/perl):

 cd t
 ./spamc.t

Getting more output from the tests
----------------------------------

The test suite can be run in a verbose mode using the TEST_VERBOSE=1
switch:

 make test TEST_VERBOSE=1

Options set using 'config'
--------------------------

The test suite accepts some configuration information to identify optional
features that should be tested, or to provide environment-specific settings
needed to test some features (such as an LDAP server or SQL server to use
testing those subsystems).   See 'config.dist' for details.

Options set using environment variables
---------------------------------------

The following environment variables affect operation of the
tests. Under most circumstances they should not be set, allowing the
tests to use default values. A full description of what all of them
do is beyond the scope of this README. If you need the degree of
customisation that they offer, you should be able to read the code in
SATest.pm to see how they are used.

See the following sections for customisations that may be required in common
configurations.  All the variables are listed here to document which may
conflict with the regression tests if they happen to be set to arbitrary
values.

SPAMD_HOST
SPAMD_PORT
SPAMD_LOCALHOST
SPAMASSASSIN_SCRIPT
SPAMC_SCRIPT
SALEARN_SCRIPT
SA_ARGS
SC_ARGS
SD_ARGS
SPAMD_FORKER
TEST_DIR
TEST_PERL_TAINT
TEST_PERL_WARN

Testing on Windows or with spamd running on another system
----------------------------------------------------------

Spamd does not run under Windows, except under Cygwin. To run the
spamc tests under Windows or any other system on which you cannot run
spamd during the tests, set the environment variable SPAMD_HOST to the
host name or ip address of the spamd daemon.

If SPAMD_HOST is not set, the regressions tests that use spamd will
start up a spamd daemon using the code in the build tree, and will
shut it down after each test script.

If SPAMD_HOST is set, you must ensure that the spamd daemon is
running before you run make test, and stop it afterwards. The spamd
daemon must run with options that include

  spamd -L -x -p 48373

The last parameter is the port on which spamd will be listening. If
you specify a different port number set the environment variable
SPAMD_PORT in the environment of the make test to be the same number.

For example, if you build SpamAssassin on a Windows system without
setting SPAMD_HOST, you would use commands

 nmake
 nmake test

which would skip all regressions tests of spamc.

If you had already build and installed SpamAssassin under Cygwin on
the same computer, then you could open a Cygwin shell, use the command

 spamd -L -x -p 48373

and then in a Windows CMD.EXE shell you could

 nmake
 set SPAMD_HOST=localhost
 nmake test

to run the spamc tests.

Testing in a FreeBSD jail
-------------------------

see https://issues.apache.org/SpamAssassin/show_bug.cgi?id=5761 for details;
basically, set SPAMD_LOCALHOST to indicate the IP address to use to contact
processes running on the same host, instead of 127.0.0.1.

 ------------------------------