README

                  Testing Apache with the Perl Test Harness
Prerequisites
-------------
You'll need to install the CPAN modules listed in:
Apache-Test/lib/Bundle/ApacheTest.pm
All you have to do to install them all in one shot is:
perl -MCPAN -e 'install Bundle::ApacheTest'

Which are also available in one tarball here:
http://perl.apache.org/~dougm/httpd-test-bundle-0.02.tar.gz

Note: Crypt::SSLeay requires OpenSSL to be installed (only required
for t/TEST -ssl): http://www.openssl.org/

For an extensive documentation see
http://perl.apache.org/docs/general/testing/testing.html
 or
http://cvs.apache.org/viewcvs.cgi/modperl-docs/src/docs/general/testing/testing.pod

Quick Start 
----------- 

If you don't care how it works and just want to run the tests, here's
how you go about doing that.

1. You need an installation of Apache. (Either 1.3 or 2.0)
2. Any DSOs you wish to use should be configured in that Apache's
   httpd.conf (the test harness will pick this configuration up)
3. Setup:
   perl Makefile.PL -apxs /path/to/apache/bin/apxs
4. Run the tests:
   t/TEST
5. Evaluate test output.


Getting a little deeper
-----------------------

The test harness will run every .t file under the t/ directory.  So
let's say you only want to run the tests for PHP.  Do this:
    t/TEST -httpd /path/to/apache/bin/httpd t/php

That will start the test server, run the .t tests under t/php and shut
down the test server.  You can also control each of these steps.

This will start the test server:
    t/TEST -httpd /path/to/apache/bin/httpd -start

This will run the PHP tests in the test environment:
    t/TEST t/php

This will stop the test server:
    t/TEST -stop

This will run the server under gdb (using -X):
    t/TEST -d gdb

Note: At this point, you have a working test environment.  You can
look in t/conf for the test server configuration files.  These are
generated by the test harness.  Once you have a working test
environment, you do not need to specify 'httpd' on the t/TEST command
line.  For instance, to start the server up again, the command
    t/TEST -start
would be sufficient.

Smoking Tests
-------------

Sometimes it's possible that the test is passing properly for the
first time, when it's run for the first time in the thread. But when
you run it again, the test might fail. It's important to run the
repetition smoke testing. For example to repeat the tests 5 times you
can run:

    t/TEST -times=5

It's also possible that a test will pass when it's run after a
particular test, but if moved to run after a different state it may
fail. For this reason it's important to ran the randomization smoking
testing with -order=random option.

Since it's important to be able to reproduce the problem with the
random testing, whenever -order=random is used, the used seed is
printed to STDERR. Which can be then fed into the future tests with:
via APACHE_TEST_SEED environment variable.

Combining these two important smoke testing techiques, one can run
tests with:

    t/TEST -times=N -order=(repeat|rotate|random)

So the tests can be repeated N times, and run in the following three
modes:

- randomize all tests
- repeat the same test N times in sequence
- rotate the whole tests suite N times

If you want this process to be automated, run:

    t/SMOKE

for configuration options and default settings run:

    t/SMOKE -help

For more information refer to the Apache::TestSmoke manpage.


Test Environment Configuration
------------------------------

The test server is configured with conf files like any normal Apache
server.  The tricky part is those conf files are generated by the
harness just prior to starting the server.  t/conf/httpd.conf is
generated by t/conf/httpd.conf.in.  If that does not exist, the
harness will generate a working configuration and will include
LoadModule (and AddModule for Apache 1.3) directives from the
httpd.conf associated with the httpd binary you are using for testing.
If t/conf/extra.conf.in exists, t/conf/extra.conf will be generated
from that, and an Include directive for that file will be put in the
generated t/conf/httpd.conf.  t/conf/apache_test_config.pm is
generated from the test configuration.  It contains all the
information about the configuration of your test server.  You can
access this information in test scripts by:
	my $env = Apache::TestConfig->thaw;
Apache::TestConfig access apache_test_config.pm and returns a hash
reference with all the information.  Look through
apache_test_config.pm, it's a lot of stuff.  Once these conf files are
generated, you have a working test environment, and they must be
'cleaned' if you wish to make chages to them.  To clean the
environment:
	t/TEST -clean
(Now you will have to specify your httpd binary when starting back up
again.)


More Information 
---------------- 

For more information on using the test harness and writing tests, see
the README in Apache-Test and the examples in Apache-Test/t.  

The test harness was written by Doug MacEachern and is discussed on
the modperl dev mailing list (dev@perl.apache.org).  

It is also included in modperl-2.0 source along with tests for
modperl-2.0.