testold(3)

NAME

       Apache::testold - Facilitates testing of Apache::* modules

SYNOPSIS

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

        # In t/*.t script (or test.pl)
        use Apache::testold qw(skip_test have_httpd);
        skip_test unless have_httpd;
        (Some more 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 mod-
       ules 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 suit-
       able 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" direc-
           tives to pass control to the module you're testing.  The "blib/"
           directories will be added to the @INC path when searching for mod-
           ules, 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 argu-
       ment 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::testold->MM_test(%params) };

       fetch

         Apache::testold->fetch($request);
         Apache::testold->fetch($user_agent, $request);

       Call this method in a test script in order to fetch a page from the
       running web server.  If you pass two arguments, the first should be an
       LWP::UserAgent object, and the second should specify the request to
       make of the server.  If you only pass one argument, it specifies the
       request to make.

       The request can be specified either by a simple string indicating the
       URI to fetch, or by a hash reference, which gives you more control over
       the request.  The following keys are recognized in the hash:

       * uri
           The URI to fetch from the server.  If the URI does not begin with
           "http", we prepend "http://localhost:$PORT" so that we make
           requests of the test server.

       * method
           The request method to use.  Default is 'GET'.

       * content
           The request content body.  Typically used to simulate HTML fill-out
           form submission for POST requests.  Default is null.

       * headers
           A hash of headers you want sent with the request.  You might use
           this to send cookies or provide some application-specific header.

       If you don't provide a 'headers' parameter and you set the 'method' to
       'POST', then we assume that you're trying to simulate HTML form submis-
       sion and we add a 'Content_Type' header with a value of 'applica-
       tion/x-www-form-urlencoded'.

       In a scalar context, fetch() returns the content of the web server's
       response.  In a list context, fetch() returns the content and the
       HTTP::Response object itself.  This can be handy if you need to check
       the response headers, or the HTTP return code, or whatever.

       static_modules

        Example: $mods = Apache::testold->static_modules('/path/to/httpd');

       This method returns a hashref whose keys are all the modules statically
       compiled into the given httpd binary.  The corresponding values are all
       1.

EXAMPLES

       No good examples yet.  Example submissions are welcome.  In the mean-
       time, see <http://forum.swarthmore.edu/~ken/modules/Apache-AuthCookie/>
       , which I'm retrofitting to use Apache::testold.

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)

perl v5.8.6                       1999-01-17                Apache::testold(3)