Apache::TestRequest - Send requests to your Apache test server
use Apache::Test qw(ok have_lwp); use Apache::TestRequest qw(GET POST); use Apache::Constants qw(HTTP_OK); plan tests => 1, have_lwp; my $res = GET '/test.html'; ok $res->code == HTTP_OK, "Request is ok";
Apache::TestRequest provides convenience functions to allow you to
make requests to your Apache test server in your test scripts. It
subclasses LWP::UserAgent, so that you have access to all if its
methods, but also exports a number of useful functions likely useful
for majority of your test requests. Users of the old Apache::test
(or Apache::testold) module, take note! Herein lie most of the
functions you'll need to use to replace Apache::test in your test
suites.
Each of the functions exported by Apache::TestRequest uses an
LWP::UserAgent object to submit the request and retrieve its
results. The return value for many of these functions is an
HTTP::Response object. See HTTP::Response for
documentation of its methods, which you can use in your tests. For
example, use the code() and content() methods to test the
response code and content of your request. Using GET, you can
perform a couple of tests using these methods like this:
use Apache::Test qw(ok have_lwp); use Apache::TestRequest qw(GET POST); use Apache::Constants qw(HTTP_OK); plan tests => 2, have_lwp; my $uri = "/test.html?foo=1&bar=2"; my $res = GET $uri; ok $res->code == HTTP_OK, "Check that the request was OK"; ok $res->content eq "foo => 1, bar => 2", "Check its content";
Note that you can also use Apache::TestRequest with
Test::Builder and its derivatives, including Test::More:
use Test::More; # ... is $res->code, HTTP_OK, "Check that the request was OK"; is $res->content, "foo => 1, bar => 2", "Check its content";
You can tell Apache::TestRequest what kind of LWP::UserAgent
object to use for its convenience functions with user_agent(). This
function uses its arguments to construct an internal global
LWP::UserAgent object that will be used for all subsequent requests
made by the convenience functions. The arguments it takes are the same
as for the LWP::UserAgent constructor. See the
LWP::UserAgent documentation for a complete list.
The user_agent() function only creates the internal
LWP::UserAgent object the first time it is called. Since this
function is called internally by Apache::TestRequest, you should
always use the reset parameter to force it to create a new global
LWP::UserAgent Object:
Apache::TestRequest::user_agent(reset => 1, %params);
user_agent() differs from LWP::UserAgent->new in two
additional ways. First, it supports an additional parameter,
keep_alive, which enables connection persistence, where the same
connection is used to process multiple requests (and, according to the
LWP::UserAgent documentation, has the effect of
loading and enabling the new experimental HTTP/1.1 protocol module).
And finally, the semantics of the requests_redirectable parameter is
different than for LWP::UserAgent in that you can pass it a boolean
value as well as an array for LWP::UserAgent. To force
Apache::TestRequest not to follow redirects in any of its convenience
functions, pass a false value to requests_redirectable:
Apache::TestRequest::user_agent(reset => 1,
requests_redirectable => 0);
If LWP is not installed, then you can still pass in an array reference
as LWP::UserAgent expects. Apache::TestRequest will examine the
array and allow redirects if the array contains more than one value or
if there is only one value and that value is not "POST":
# Always allow redirection.
my $redir = have_lwp() ? [qw(GET HEAD POST)] : 1;
Apache::TestRequest::user_agent(reset => 1,
requests_redirectable => $redir);
But note that redirection will not work with POST unless LWP is
installed. It's best, therefore, to check have_lwp before running
tests that rely on a redirection from POST.
Sometimes it is desireable to have Apache::TestRequest remember
cookies sent by the pages you are testing and send them back to the
server on subsequent requests. This is especially necessary when
testing pages whose functionality relies on sessions or the presence
of preferences stored in cookies.
By default, LWP::UserAgent does not remember cookies between
requests. You can tell it to remember cookies between request by
adding:
Apache::TestRequest::user_agent(cookie_jar => {});
before issuing the requests.
Apache::TestRequest exports a number of functions that will likely
prove convenient for use in the majority of your request tests.
Each function also takes a number of optional arguments.
By default a request will follow redirects retrieved from the server. To
prevent this behavior, pass a false value to a redirect_ok
parameter:
my $res = GET $uri, redirect_ok => 0;
Alternately, if all of your tests need to disable redirects, tell
Apache::TestRequest to use an LWP::UserAgent object that
disables redirects:
Apache::TestRequest::user_agent( reset => 1,
requests_redirectable => 0 );
If you need to force an SSL request to use a particular SSL
certificate, pass the name of the certificate via the cert
parameter:
my $res = GET $uri, cert => 'my_cert';
If you need to add content to your request, use the content
parameter:
my $res = GET $uri, content => 'hello world!';
UPLOAD() and its friends.
my $res = GET $uri;
Sends a simple GET request to the Apache test server. Returns an
HTTP::Response object.
You can also supply additional headers to be sent with the request by
adding their name/value pairs after the url parameter, for example:
my $res = GET $url, 'Accept-Language' => 'de,en-us,en;q=0.5';
A shortcut function for GET($uri)->as_string.
A shortcut function for GET($uri)->content.
Use this function when your test is outputting content that you need
to check, and you want to make sure that the request was successful
before comparing the contents of the request. If the request was
unsuccessful, GET_BODY_ASSERT will return an error
message. Otherwise it will simply return the content of the request
just as GET_BODY would.
A shortcut function for GET($uri)->is_success.
A shortcut function for GET($uri)->code.
Throws out the content of the request, and returns the string
representation of the request. Since the body has been thrown out, the
representation will consist solely of the headers. Furthermore,
GET_HEAD inserts a "#" at the beginning of each line of the return
string, so that the contents are suitable for printing to STDERR
during your tests without interfering with the workings of
Test::Harness.
my $res = HEAD $uri;
Sends a HEAD request to the Apache test server. Returns an
HTTP::Response object.
A shortcut function for HEAD($uri)->as_string.
A shortcut function for HEAD($uri)->content. Of course, this
means that it will likely return nothing.
Use this function when your test is outputting content that you need
to check, and you want to make sure that the request was successful
before comparing the contents of the request. If the request was
unsuccessful, HEAD_BODY_ASSERT will return an error
message. Otherwise it will simply return the content of the request
just as HEAD_BODY would.
A shortcut function for GET($uri)->is_success.
A shortcut function for GET($uri)->code.
Throws out the content of the request, and returns the string
representation of the request. Since the body has been thrown out, the
representation will consist solely of the headers. Furthermore,
GET_HEAD inserts a "#" at the beginning of each line of the return
string, so that the contents are suitable for printing to STDERR
during your tests without interfering with the workings of
Test::Harness.
my $res = PUT $uri;
Sends a simple PUT request to the Apache test server. Returns an
HTTP::Response object.
A shortcut function for PUT($uri)->as_string.
A shortcut function for PUT($uri)->content.
Use this function when your test is outputting content that you need
to check, and you want to make sure that the request was successful
before comparing the contents of the request. If the request was
unsuccessful, PUT_BODY_ASSERT will return an error
message. Otherwise it will simply return the content of the request
just as PUT_BODY would.
A shortcut function for PUT($uri)->is_success.
A shortcut function for PUT($uri)->code.
Throws out the content of the request, and returns the string
representation of the request. Since the body has been thrown out, the
representation will consist solely of the headers. Furthermore,
PUT_HEAD inserts a "#" at the beginning of each line of the return
string, so that the contents are suitable for printing to STDERR
during your tests without interfering with the workings of
Test::Harness.
my $res = POST $uri, [ arg => $val, arg2 => $val ];
Sends a POST request to the Apache test server and returns an
HTTP::Response object. An array reference of parameters passed as
the second argument will be submitted to the Apache test server as the
POST content. Parameters corresponding to those documented in
Optional Parameters can follow the optional array reference of parameters, or after
$uri.
To upload a chunk of data, simply use:
my $res = POST $uri, content => $data;
A shortcut function for POST($uri, @args)->content.
A shortcut function for POST($uri, @args)->content.
Use this function when your test is outputting content that you need
to check, and you want to make sure that the request was successful
before comparing the contents of the request. If the request was
unsuccessful, POST_BODY_ASSERT will return an error
message. Otherwise it will simply return the content of the request
just as POST_BODY would.
A shortcut function for POST($uri, @args)->is_success.
A shortcut function for POST($uri, @args)->code.
Throws out the content of the request, and returns the string
representation of the request. Since the body has been thrown out, the
representation will consist solely of the headers. Furthermore,
POST_HEAD inserts a "#" at the beginning of each line of the return
string, so that the contents are suitable for printing to STDERR
during your tests without interfering with the workings of
Test::Harness.
my $res = UPLOAD $uri, \@args, filename => $filename;
Sends a request to the Apache test server that includes an uploaded file. Other POST parameters can be passed as a second argument as an array reference.
Apache::TestRequest will read in the contents of the file named via
the filename parameter for submission to the server. If you'd
rather, you can submit use the content parameter instead of
filename, and its value will be submitted to the Apache server as
file contents:
my $res = UPLOAD $uri, undef, content => "This is file content";
The name of the file sent to the server will simply be "b". Note that
in this case, you cannot pass other POST arguments to UPLOAD() --
they would be ignored.
A shortcut function for UPLOAD($uri, @params)->content.
Use this function when your test is outputting content that you need
to check, and you want to make sure that the request was successful
before comparing the contents of the request. If the request was
unsuccessful, UPLOAD_BODY_ASSERT will return an error
message. Otherwise it will simply return the content of the request
just as UPLOAD_BODY would.
my $res = OPTIONS $uri;
Sends an OPTIONS request to the Apache test server. Returns an
HTTP::Response object with the Allow header, indicating which
methods the server supports. Possible methods include OPTIONS,
GET, HEAD and POST. This function thus can be useful for
testing what options the Apache server supports. Consult the HTTPD 1.1
specification, section 9.2, at
http://www.faqs.org/rfcs/rfc2616.html for more information.
Apache::TestRequest also includes a few helper functions to aid in
the creation of urls used in the functions above.
module2path
$path = Apache::TestRequest::module2path($module_name);
Convert a module name to a path, safe for use in the various request
methods above. e.g. :: can't be used in URLs on win32. For example:
$path = Apache::TestRequest::module2path('Foo::Bar');
returns:
/Foo__Bar
module2url
$url = Apache::TestRequest::module2url($module); $url = Apache::TestRequest::module2url($module, \%options);
Convert a module name to a full URL including the current
configurations hostname:port and sets module accordingly.
$url = Apache::TestRequest::module2url('Foo::Bar');
returns:
http://$hostname:$port/Foo__Bar
The default scheme used is http. You can override this by passing
your preferred scheme into an optional second param. For example:
$module = 'MyTestModule::TestHandler';
$url = Apache::TestRequest::module2url($module, {scheme => 'https'});
returns:
https://$hostname:$port/MyTestModule__TestHandler
You may also override the default path with a path of your own:
$module = 'MyTestModule::TestHandler';
$url = Apache::TestRequest::module2url($module, {path => '/foo'});
returns:
http://$hostname:$port/foo
The following environment variables can affect the behavior of
Apache::TestRequest:
APACHE_TEST_PRETEND_NO_LWP is set to a
true value, Apache::TestRequest will pretend that LWP is not
available so one can test whether the test suite will survive on a
system which doesn't have libwww-perl installed.
APACHE_TEST_HTTP_09_OK is set to a
true value, Apache::TestRequest will allow HTTP/0.9 responses
from the server to proceed. The default behavior is to die if
the response protocol is not either HTTP/1.0 or HTTP/1.1.
Apache::Test is the main Apache testing module. Use it to set up your tests, create a plan, and to ensure that you have the Apache version and modules you need.
Use Apache::TestMM in your Makefile.PL to set up your distribution for testing.
Doug MacEachern with contributions from Geoffrey Young, Philippe M. Chiasson, Stas Bekman and others. Documentation by David Wheeler.
Questions can be asked at the test-dev <at> httpd.apache.org list. For more information see: http://httpd.apache.org/test/ and http://perl.apache.org/docs/general/testing/testing.html.