Patch for easy testing of Apache::* modules

[Ken Williams <ke...@forum.swarthmore.edu>]

Hi list,

I've been working on the Apache::test module, trying to make it easier
for people to build Apache::* modules with useful test suites.  By
'useful', I mean a 'make test' process that actually starts an Apache
server and makes some queries of that server.  

I've been doing this myself for a good while now with some of my own
Apache::* modules (like Apache::AuthCookie), but the process is a bit
unmanageable in the decentralized form I've been using.  I've also had a
couple requests to modularize the process and make it available to
others. So I decided to submit patches to Apache::test, distributed with
mod_perl itself, so that we could have a standard process for building
these test suites.

The patch for this (against the current CVS version) is attached.  The
[new] documentation (run through pod2text) is below.  I'm hoping someone
with commit privileges on the CVS tree can get this in there.

Comments quite welcome.  Let me know if line endings or anything are
messed up in the attachment.

  -Ken



---------------------------------------------------------
NAME
    Apache::Test - Facilitates testing of Apache::* modules

SYNOPSIS
     # In Makefile.PL
     use Apache::test;
     my %params = Apache::test->get_test_params();
     Apache::test->write_httpd_conf(%params, include => $more_directives);
     *MY::test = sub { Apache::test->MM_test(%params) };

     # In t/*.t script (or test.pl)
     (Some methods of Doug's that I haven't reviewed or documented yet)

DESCRIPTION
    This module helps authors of Apache::* modules write test suites that
    can query an actual running Apache server with mod_perl and their
    modules loaded into it. Its functionality is generally separated into
    methods that go in a Makefile.PL to configure, start, and stop the
    server, and methods that go in one of the test scripts to make HTTP
    queries and manage the results.

METHODS
  get_test_params()

    This will ask the user a few questions about where the httpd binary is,
    and what user/group/port should be used when running the server. It will
    return a hash of the information it discovers. This hash is suitable for
    passing to the `write_httpd_conf()' method.

  write_httpd_conf(%params)

    This will write a basic `httpd.conf' file suitable for starting a HTTP
    server during the 'make test' stage. A hash of key/value pairs that
    affect the written file can be passed as arguments. The following keys
    are recognized:

    * conf_file
        The path to the file that will be created. Default is
        't/httpd.conf'.

    * port
        The port that the Apache server will listen on.

    * user
        The user that the Apache server will run as.

    * group
        The group that the Apache server will run as.

    * include
        Any additional text you want added at the end of the config file.
        Typically you'll have some `PerlModule' and `Perl*Handler'
        directives to pass control to the module you're testing. The `blib/'
        directories will be added to the `@INC' path when searching for
        modules, so that's nice.

  MM_test(%params)

    This method helps write a Makefile that supports running a web server
    during the 'make test' stage. When you execute 'make test', 'make' will
    run 'make start_httpd', 'make run_tests', and 'make kill_httpd' in
    sequence. You can also run these commands independently if you want.

    Pass the hash of parameters returned by `get_test_params()' as an
    argument to `MM_test()'.

    To patch into the ExtUtils::MakeMaker wizardry (voodoo?), typically
    you'll do the following in your Makefile.PL:

      *MY::test = sub { Apache::test->MM_test(%params) };

EXAMPLES
    No good examples yet. Examples are welcome. In the meantime, see the
    section on "/forum.swarthmore.edu/~ken/modules/Apache-AuthCookie/" in
    the http: manpage , which I'm retrofitting to use Apache::test.

TO DO
    The MM_test method doesn't try to be very smart, it just writes the text
    that seems to work in my configuration. I am morally against using the
    'make' command for installing Perl modules (though of course I do it
    anyway), so I haven't looked into this very much. Send bug reports or
    better (patches).

    I've got lots of code in my Apache::AuthCookie module (etc.) that
    assists in actually making the queries of the running server. I plan to
    add that to this module, but first I need to compare what's already here
    that does the same stuff.

KUDOS
    To Doug MacEachern for writing the first version of this module.

    To caelum@debian.org (Rafael Kitover) for contributing the code to parse
    existing httpd.conf files for --enable-shared=max and DSOs.

CAVEATS
    Except for making sure that the mod_perl distribution itself can run
    'make test' okay, I haven't tried very hard to keep compatibility with
    older versions of this module. In particular MM_test() has changed and
    probably isn't usable in the old ways, since some of its assumptions are
    gone. But none of this was ever documented, and MM_test() doesn't seem
    to actually be used anywhere in the mod_perl disribution, so I don't
    feel so bad about it.

AUTHOR
    Doug MacEachern (original version)

    Ken Williams (latest changes and this documentation)