=head1 NAME Apache::test - Facilitates testing of Apache::* modules =head1 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) use Apache::test qw(skip_test have_httpd); skip_test unless have_httpd; (Some more methods of Doug's that I haven't reviewed or documented yet) =head1 Description This module helps authors of C 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 I 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. =head1 Methods =head2 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 C method. =head2 write_httpd_conf(%params) This will write a basic I file suitable for starting a HTTP server during the C stage. A hash of key/value pairs that affect the written file can be passed as arguments. The following keys are recognized: =over 4 =item * conf_file The path to the file that will be created. Default is I. =item * port The port that the Apache server will listen on. =item * user The user that the Apache server will run as. =item * group The group that the Apache server will run as. =item * include Any additional text you want added at the end of the config file. Typically you'll have some C and C directives to pass control to the module you're testing. The C directories will be added to the C<@INC> path when searching for modules, so that's nice. =back =head2 MM_test(%params) This method helps write a Makefile that supports running a web server during the C stage. When you execute C, C will run C, C, and C in sequence. You can also run these commands independently if you want. Pass the hash of parameters returned by C as an argument to C. To patch into the C wizardry (voodoo?), typically you'll do the following in your I: *MY::test = sub { Apache::test->MM_test(%params) }; =head2 fetch Apache::test->fetch($request); Apache::test->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 C 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: =over 4 =item * uri The URI to fetch from the server. If the URI does not begin with C, we prepend C so that we make requests of the test server. =item * method The request method to use. Default is C. =item * content The request content body. Typically used to simulate HTML fill-out form submission for C requests. Default is null. =item * headers A hash of headers you want sent with the request. You might use this to send cookies or provide some application-specific header. =back If you don't provide a C parameter and you set the C to C, then we assume that you're trying to simulate HTML form submission and we add a C header with a value of C. In a scalar context, C returns the content of the web server's response. In a list context, C returns the content and the C object itself. This can be handy if you need to check the response headers, or the HTTP return code, or whatever. =head2 static_modules Example: $mods = Apache::test->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. =head1 Examples No good examples yet. Example submissions are welcome. In the meantime, see http://forum.swarthmore.edu/~ken/modules/Apache-AuthCookie/ , which I'm retrofitting to use C. =head1 To Do The C 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 C 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 C 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. =head1 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 C<--enable-shared=max> and DSOs. =head1 Caveats Except for making sure that the mod_perl distribution itself can run C okay, I haven't tried very hard to keep compatibility with older versions of this module. In particular C 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 C doesn't seem to actually be used anywhere in the mod_perl disribution, so I don't feel so bad about it. =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. =over =item * The L =back =head1 Authors =over =item * Doug MacEachern =item * Ken Williams =back Only the major authors are listed above. For contributors see the Changes file. =cut