The Perl Framework, which is part of the same suite, concentrates on testing the configuration and components of Apache (the core binary and its associated support modules) on your platform to ensure the configuration works and the modules have compiled and installed properly.

By now you're probably thinking this sounds pretty useless -- once you've installed Apache, especially from a pre-built binary installer, why would you want (or need) to test it?

The simple answer is that many modules -- even the core ones -- rely on the functionality of external libraries. If you periodically update your system, either manually or automatically through something like the RedHat Network, then you could break your Apache installation without even realizing it. The problem could be so obscure that it never turns up in standard tests and investigations, and you probably wouldn't know about it until a user complains.

In a deployment situation, whether installing Apache on a number of identical machines or on a range of different platforms, you must ensure that your Apache installation is as stable and compatible as possible. Often simply starting Apache or using the configtest argument to apachectl will not be enough to highlight a potential problem.

The Perl Framework was originally designed to help test the mod_perl v2.0 extension for Apache. While the framework is compatible with both Apache 1.3.x and Apache 2.0, the modular nature of Apache 2.0 makes the process significantly easier, and the tests provided by the framework in 2.0 are much more extensive.

Installing the Framework

To use the Framework you'll need Perl and a variety of additional modules, as well as the main HTTPD-Test distribution itself. If you haven't already downloaded the HTTPD-Test distribution, use the following to download the latest version from the Apache CVS server (the password is 'anoncvs'):

$ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
$ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co httpd-test

Once you have that available, the easiest way to get the necessary Perl modules is through CPAN:

perl -MCPAN -e 'install Bundle::ApacheTest'

The above will download and install all the modules required by the Perl framework. If you've got CPAN set to follow prerequisite modules, it will download or update all of the other required modules.

The next step is setting up and building the Perl framework. First, change to the perl-framework directory within the httpd-test directory. If you are using a dynamic version of Apache, you should have apxs tool, and you can build the suite using the -apxs command line option and specify the tools location, e.g.,:

perl Makefile.PL -apxs /export/http/apache2/bin/apxs

Otherwise, just use:

Perl Makefile.PL

This will build the necessary components for you to continue and run the actual tests.

The next step is run make to create all the necessary files and get ready to run the tests.

Running the Tests

The tests themselves are located in the t directory below the main perl-framework directory. One global script, TEST, provides an interface to the underlying test routines and summarizes the output of the various tests for you. You can also run tests individually by specifically requesting them on the command line.

Before you start, bear in mind how the tests actually work. The Perl framework is designed to test the modules and components in an Apache installation. That means it uses the Apache installation directly -- it doesn't build or install a copy for you. Therefore, your Apache configuration should be exactly as you are planning to use it, and you must ensure it's the right version of Apache, configured during build time with the right options, and that your DSO modules are up to date and installed (assuming you are using them).

The framework does not use either your configuration file or documents from your Web site. Test documents are included with the distribution, located in the t/htdocs directory. The configuration file is generated just before the test sequence starts running the actual tests, which is almost immediately before the Apache server is started. You can set certain options when you start the TEST script. For more in-depth modifications, the best way is to add or edit the file t/conf/extra.conf.in with your desired settings. This will be incorporated into the temporary config file generated before the tests are executed.