/ 
Apache-Test-1.04
River stage three • 70 direct dependents • 144 total dependents
/ Apache::TestRequest

NAME

Apache::TestRequest - Send requests to your Apache test server

SYNOPSIS

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";

DESCRIPTION

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";

CONFIGURATION FUNCTION

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. Apache::TestRequest never follows redirects for POST requests. However, it either follows redirects for all other kinds of requests, or it doesn't. Thus requests_redirectable is a boolean value instead of the array reference that LWP::UserAgent expects. Thus, 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);

FUNCTIONS

Apache::TestRequest exports a number of functions that will likely prove convenient for use in the majority of your request tests.

Optional Parameters

Each function also takes a number of optional arguments.

redirect_ok

By default they 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 );
cert

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';
content

If you need to add content to your request, use the content parameter:

my $res = GET $uri, content = 'hello world!';
filename

The name of a local file on the file system to be sent to the Apache test server via UPLOAD() and its friends.

The Functions

GET
my $res = GET $uri;

Sends a simple GET request to the Apache test server. Returns an HTTP::Response object.

GET_STR

A shortcut function for GET($uri)->as_string.

GET_BODY

A shortcut function for GET($uri)->content.

GET_BODY_ASSERT

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.

GET_OK

A shortcut function for GET($uri)->is_success.

GET_RC

A shortcut function for GET($uri)->code.

GET_HEAD

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.

HEAD_STR

A shortcut function for HEAD($uri)->as_string.

HEAD_BODY

A shortcut function for HEAD($uri)->content. Of course, this means that it will likely return nothing.

HEAD_BODY_ASSERT

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.

HEAD_OK

A shortcut function for GET($uri)->is_success.

HEAD_RC

A shortcut function for GET($uri)->code.

HEAD_HEAD

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.

PUT
my $res = PUT $uri;

Sends a simple PUT request to the Apache test server. Returns an HTTP::Response object.

PUT_STR

A shortcut function for PUT($uri)->as_string.

PUT_BODY

A shortcut function for PUT($uri)->content.

PUT_BODY_ASSERT

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.

PUT_OK

A shortcut function for PUT($uri)->is_success.

PUT_RC

A shortcut function for PUT($uri)->code.

PUT_HEAD

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.

POST
my $res = POST $uri, arg  => $val, arg2 => $val;

Sends a POST request to the Apache test server and returns an HTTP::Response object. Any parameters passed after $uri that do not correspond to those documented in Optional Parameters will be submitted to the Apache test server as the POST content.

POST_STR

A shortcut function for POST($uri, @args)->content.

POST_BODY

A shortcut function for POST($uri, @args)->content.

POST_BODY_ASSERT

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.

POST_OK

A shortcut function for POST($uri, @args)->is_success.

POST_RC

A shortcut function for POST($uri, @args)->code.

POST_HEAD

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.

UPLOAD
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.

UPLOAD_BODY

A shortcut function for UPLOAD($uri, @params)->content.

UPLOAD_BODY_ASSERT

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.

OPTIONS
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.

ENVIRONMENT VARIABLES

The following environment variables can affect the behavior of Apache::TestRequest:

APACHE_TEST_PRETEND_NO_LWP

If the environment variable 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.

SEE ALSO

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.

AUTHOR

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.