Apache:...tRequest(3)

okay bestie, welcome to Apache:...tRequest(3) — manual name, from the User Contributed Perl Documentation crew. We're talking about Apache::TestRequest, and it's literally here to send requests to your Apache test server. No cap, this is the convenience-function headquarters for your test scripts ✨.

💖 NAME 💖

• Apache::TestRequest — Send requests to your Apache test server 🫶

✨ SYNOPSIS ✨

Slap this into your test and vibe check the response:

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 gives you convenience functions so you can make requests to your Apache test server inside your test scripts. It subclasses LWP::UserAgent, so you get access to all of its methods, and it also exports a number of useful functions likely useful for the 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 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. This is a big deal, bestie — don't skip the check 💀.

Sometimes it is desirable 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 requests by adding:

Apache::TestRequest::user_agent(cookie_jar => {});

before issuing the requests 💖.

💖 FUNCTIONS 💖

Apache::TestRequest exports a whole squad of functions that are gonna be your besties in basically every request test you write, fr fr.

🌸 Optional Parameters 🌸

Every single one of these functions also takes some optional arguments, and they're lowkey iconic:

• redirect_ok — okay so by default, a request will follow redirects it gets back from the server. If you don't want that (and sometimes you really don't), just pass a false value to a redirect_ok parameter:

my $res = GET $uri, redirect_ok => 0;

Or, alternate route: if all your tests need redirects off, just tell Apache::TestRequest to use an LWP::UserAgent object that disables redirects entirely:

Apache::TestRequest::user_agent( reset => 1,
                                 requests_redirectable => 0 );

• cert — need to force an SSL request to use one specific SSL certificate? Pass the certificate's name through the cert parameter, easy peasy:

my $res = GET $uri, cert => 'my_cert';

• content — gotta add content to your request? The content parameter has you covered bestie:

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

• filename — the name of a local file on the file system that gets 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 and hands you back an HTTP::Response object. That's it, that's the vibe.

You can also slip in extra headers to send along with the request by dropping their name/value pairs after the url parameter, like so:

my $res = GET $url, 'Accept-Language' => 'de,en-us,en;q=0.5';

GET_STR

A shortcut function for GET($uri)->as_string. Cute, quick, does the thing. ✨

GET_BODY

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

GET_BODY_ASSERT

Use this one when your test is outputting content you need to check, and you wanna make sure the request actually succeeded before you go comparing the contents of the request. If the request was unsuccessful, GET_BODY_ASSERT will return an error message. Otherwise it just returns the content of the request, exactly like GET_BODY would. Guardian angel behavior honestly. 🫶

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 got yeeted, that representation is gonna consist solely of the headers. And on top of that, GET_HEAD inserts a # at the beginning of each line of the return string, so the contents are suitable for printing to STDERR while your tests run without interfering with the workings of Test::Harness. Big brain energy. 💅

HEAD

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 it will likely return nothing. 🙈 That's just how HEAD works, bestie.

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. An array reference of parameters passed as the second argument gets 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. Flexible king. 👑

Wanna upload a chunk of data? Literally just:

my $res = POST $uri, content => $data;

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. Noted. 📝

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. So this function is genuinely 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. Go read the spec bestie, it's giving scholarship. 📚

---

🦋 URL Manipulation Functions 🦋

Apache::TestRequest also includes a few helper functions to aid in the creation of urls used in the functions above. Little helpers, we stan.

module2path

$path = Apache::TestRequest::module2path($module_name);

Convert a module name to a path that's 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 configuration's 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

Customization? We love to see it. 💜

---

🌈 ENVIRONMENT VARIABLES 🌈

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

• APACHE_TEST_PRETEND_NO_LWP — if this environment variable is set to a true value, Apache::TestRequest will pretend that LWP is not available, so you can test whether your test suite will survive on a system that doesn't have libwww-perl installed. Fake it till you make it, but for testing. 🎭
• APACHE_TEST_HTTP_09_OK — if this environment variable 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. So yeah, without this set, HTTP/0.9 will absolutely end you. 💀

---

⭐ 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. The main character, honestly. 👑

Use Apache::TestMM in your Makefile.PL to set up your distribution for testing.

👑 AUTHOR 💅

okay so this page was written by Doug MacEachern, with contributions from Geoffrey Young, Philippe M. Chiasson, Stas Bekman and others — literal icons, all of them, no cap 🫶

The documentation? That was David Wheeler. We stan a docs king 👑

Got questions? Bestie, you are so not alone — hit up the test-dev <at> httpd.apache.org list and the whole group chat will help you out 😭💖

Want more info? It's all right here:

• http://httpd.apache.org/test/
• http://perl.apache.org/docs/general/testing/testing.html

---

fr fr go read those links, they're giving main character energy and they'll clear up anything this page didn't. iykyk ✨

🌸 that's the whole page, bestie — slay, you made it to the end 🎀

⭐ sign-off time: this lil masterpiece is from perl v5.42.3, dated 2023-10-21, and it lives its life as Apache:...tRequest(3). periodt 💅💜