1Apache::TestRequest(3)User Contributed Perl DocumentationApache::TestRequest(3)
2
6 Apache::TestRequest - Send requests to your Apache test server
7
9 use Apache::Test qw(ok have_lwp);
10 use Apache::TestRequest qw(GET POST);
11 use Apache::Constants qw(HTTP_OK);
12 plan tests => 1, have_lwp;
14 my $res = GET '/test.html';
16 ok $res->code == HTTP_OK, "Request is ok";
17
19 Apache::TestRequest provides convenience functions to allow you to make
20 requests to your Apache test server in your test scripts. It subclasses
21 "LWP::UserAgent", so that you have access to all if its methods, but
22 also exports a number of useful functions likely useful for majority of
23 your test requests. Users of the old "Apache::test" (or
24 "Apache::testold") module, take note! Herein lie most of the functions
25 you'll need to use to replace "Apache::test" in your test suites.
26 Each of the functions exported by "Apache::TestRequest" uses an
28 "LWP::UserAgent" object to submit the request and retrieve its results.
29 The return value for many of these functions is an HTTP::Response
30 object. See HTTP::Response for documentation of its methods, which you
31 can use in your tests. For example, use the "code()" and "content()"
32 methods to test the response code and content of your request. Using
33 "GET", you can perform a couple of tests using these methods like this:
34 use Apache::Test qw(ok have_lwp);
36 use Apache::TestRequest qw(GET POST);
37 use Apache::Constants qw(HTTP_OK);
38 plan tests => 2, have_lwp;
40 my $uri = "/test.html?foo=1&bar=2";
42 my $res = GET $uri;
43 ok $res->code == HTTP_OK, "Check that the request was OK";
44 ok $res->content eq "foo => 1, bar => 2", "Check its content";
45 Note that you can also use "Apache::TestRequest" with "Test::Builder"
47 and its derivatives, including "Test::More":
48 use Test::More;
50 # ...
51 is $res->code, HTTP_OK, "Check that the request was OK";
52 is $res->content, "foo => 1, bar => 2", "Check its content";
53
55 You can tell "Apache::TestRequest" what kind of "LWP::UserAgent" object
56 to use for its convenience functions with "user_agent()". This function
57 uses its arguments to construct an internal global "LWP::UserAgent"
58 object that will be used for all subsequent requests made by the
59 convenience functions. The arguments it takes are the same as for the
60 "LWP::UserAgent" constructor. See the "LWP::UserAgent" documentation
61 for a complete list.
62 The "user_agent()" function only creates the internal "LWP::UserAgent"
64 object the first time it is called. Since this function is called
65 internally by "Apache::TestRequest", you should always use the "reset"
66 parameter to force it to create a new global "LWP::UserAgent" Object:
67 Apache::TestRequest::user_agent(reset => 1, %params);
69 "user_agent()" differs from "LWP::UserAgent->new" in two additional
71 ways. First, it supports an additional parameter, "keep_alive", which
72 enables connection persistence, where the same connection is used to
73 process multiple requests (and, according to the "LWP::UserAgent"
74 documentation, has the effect of loading and enabling the new
75 experimental HTTP/1.1 protocol module).
76 And finally, the semantics of the "requests_redirectable" parameter is
78 different than for "LWP::UserAgent" in that you can pass it a boolean
79 value as well as an array for "LWP::UserAgent". To force
80 "Apache::TestRequest" not to follow redirects in any of its convenience
81 functions, pass a false value to "requests_redirectable":
82 Apache::TestRequest::user_agent(reset => 1,
84 requests_redirectable => 0);
85 If LWP is not installed, then you can still pass in an array reference
87 as "LWP::UserAgent" expects. "Apache::TestRequest" will examine the
88 array and allow redirects if the array contains more than one value or
89 if there is only one value and that value is not "POST":
90 # Always allow redirection.
92 my $redir = have_lwp() ? [qw(GET HEAD POST)] : 1;
93 Apache::TestRequest::user_agent(reset => 1,
94 requests_redirectable => $redir);
95 But note that redirection will not work with "POST" unless LWP is
97 installed. It's best, therefore, to check "have_lwp" before running
98 tests that rely on a redirection from "POST".
99 Sometimes it is desireable to have "Apache::TestRequest" remember
101 cookies sent by the pages you are testing and send them back to the
102 server on subsequent requests. This is especially necessary when
103 testing pages whose functionality relies on sessions or the presence of
104 preferences stored in cookies.
105 By default, "LWP::UserAgent" does not remember cookies between
107 requests. You can tell it to remember cookies between request by
108 adding:
109 Apache::TestRequest::user_agent(cookie_jar => {});
111 before issuing the requests.
113
115 "Apache::TestRequest" exports a number of functions that will likely
116 prove convenient for use in the majority of your request tests.
117 Optional Parameters
119 Each function also takes a number of optional arguments.
120 redirect_ok
122 By default a request will follow redirects retrieved from the
123 server. To prevent this behavior, pass a false value to a
124 "redirect_ok" parameter:
125 my $res = GET $uri, redirect_ok => 0;
127 Alternately, if all of your tests need to disable redirects, tell
129 "Apache::TestRequest" to use an "LWP::UserAgent" object that
130 disables redirects:
131 Apache::TestRequest::user_agent( reset => 1,
133 requests_redirectable => 0 );
134 cert
136 If you need to force an SSL request to use a particular SSL
137 certificate, pass the name of the certificate via the "cert"
138 parameter:
139 my $res = GET $uri, cert => 'my_cert';
141 content
143 If you need to add content to your request, use the "content"
144 parameter:
145 my $res = GET $uri, content => 'hello world!';
147 filename
149 The name of a local file on the file system to be sent to the
150 Apache test server via "UPLOAD()" and its friends.
151 The Functions
153 GET
154 my $res = GET $uri;
156 Sends a simple GET request to the Apache test server. Returns an
158 "HTTP::Response" object.
159 You can also supply additional headers to be sent with the request by
161 adding their name/value pairs after the "url" parameter, for example:
162 my $res = GET $url, 'Accept-Language' => 'de,en-us,en;q=0.5';
164 GET_STR
166 A shortcut function for "GET($uri)->as_string".
168 GET_BODY
170 A shortcut function for "GET($uri)->content".
172 GET_BODY_ASSERT
174 Use this function when your test is outputting content that you need to
176 check, and you want to make sure that the request was successful before
177 comparing the contents of the request. If the request was unsuccessful,
178 "GET_BODY_ASSERT" will return an error message. Otherwise it will
179 simply return the content of the request just as "GET_BODY" would.
180 GET_OK
182 A shortcut function for "GET($uri)->is_success".
184 GET_RC
186 A shortcut function for "GET($uri)->code".
188 GET_HEAD
190 Throws out the content of the request, and returns the string
192 representation of the request. Since the body has been thrown out, the
193 representation will consist solely of the headers. Furthermore,
194 "GET_HEAD" inserts a "#" at the beginning of each line of the return
195 string, so that the contents are suitable for printing to STDERR during
196 your tests without interfering with the workings of "Test::Harness".
197 HEAD
199 my $res = HEAD $uri;
201 Sends a HEAD request to the Apache test server. Returns an
203 "HTTP::Response" object.
204 HEAD_STR
206 A shortcut function for "HEAD($uri)->as_string".
208 HEAD_BODY
210 A shortcut function for "HEAD($uri)->content". Of course, this means
212 that it will likely return nothing.
213 HEAD_BODY_ASSERT
215 Use this function when your test is outputting content that you need to
217 check, and you want to make sure that the request was successful before
218 comparing the contents of the request. If the request was unsuccessful,
219 "HEAD_BODY_ASSERT" will return an error message. Otherwise it will
220 simply return the content of the request just as "HEAD_BODY" would.
221 HEAD_OK
223 A shortcut function for "GET($uri)->is_success".
225 HEAD_RC
227 A shortcut function for "GET($uri)->code".
229 HEAD_HEAD
231 Throws out the content of the request, and returns the string
233 representation of the request. Since the body has been thrown out, the
234 representation will consist solely of the headers. Furthermore,
235 "GET_HEAD" inserts a "#" at the beginning of each line of the return
236 string, so that the contents are suitable for printing to STDERR during
237 your tests without interfering with the workings of "Test::Harness".
238 PUT
240 my $res = PUT $uri;
242 Sends a simple PUT request to the Apache test server. Returns an
244 "HTTP::Response" object.
245 PUT_STR
247 A shortcut function for "PUT($uri)->as_string".
249 PUT_BODY
251 A shortcut function for "PUT($uri)->content".
253 PUT_BODY_ASSERT
255 Use this function when your test is outputting content that you need to
257 check, and you want to make sure that the request was successful before
258 comparing the contents of the request. If the request was unsuccessful,
259 "PUT_BODY_ASSERT" will return an error message. Otherwise it will
260 simply return the content of the request just as "PUT_BODY" would.
261 PUT_OK
263 A shortcut function for "PUT($uri)->is_success".
265 PUT_RC
267 A shortcut function for "PUT($uri)->code".
269 PUT_HEAD
271 Throws out the content of the request, and returns the string
273 representation of the request. Since the body has been thrown out, the
274 representation will consist solely of the headers. Furthermore,
275 "PUT_HEAD" inserts a "#" at the beginning of each line of the return
276 string, so that the contents are suitable for printing to STDERR during
277 your tests without interfering with the workings of "Test::Harness".
278 POST
280 my $res = POST $uri, [ arg => $val, arg2 => $val ];
282 Sends a POST request to the Apache test server and returns an
284 "HTTP::Response" object. An array reference of parameters passed as the
285 second argument will be submitted to the Apache test server as the POST
286 content. Parameters corresponding to those documented in Optional
287 Parameters can follow the optional array reference of parameters, or
288 after $uri.
289 To upload a chunk of data, simply use:
291 my $res = POST $uri, content => $data;
293 POST_STR
295 A shortcut function for "POST($uri, @args)->content".
297 POST_BODY
299 A shortcut function for "POST($uri, @args)->content".
301 POST_BODY_ASSERT
303 Use this function when your test is outputting content that you need to
305 check, and you want to make sure that the request was successful before
306 comparing the contents of the request. If the request was unsuccessful,
307 "POST_BODY_ASSERT" will return an error message. Otherwise it will
308 simply return the content of the request just as "POST_BODY" would.
309 POST_OK
311 A shortcut function for "POST($uri, @args)->is_success".
313 POST_RC
315 A shortcut function for "POST($uri, @args)->code".
317 POST_HEAD
319 Throws out the content of the request, and returns the string
321 representation of the request. Since the body has been thrown out, the
322 representation will consist solely of the headers. Furthermore,
323 "POST_HEAD" inserts a "#" at the beginning of each line of the return
324 string, so that the contents are suitable for printing to STDERR during
325 your tests without interfering with the workings of "Test::Harness".
326 UPLOAD
328 my $res = UPLOAD $uri, \@args, filename => $filename;
330 Sends a request to the Apache test server that includes an uploaded
332 file. Other POST parameters can be passed as a second argument as an
333 array reference.
334 "Apache::TestRequest" will read in the contents of the file named via
336 the "filename" parameter for submission to the server. If you'd rather,
337 you can submit use the "content" parameter instead of "filename", and
338 its value will be submitted to the Apache server as file contents:
339 my $res = UPLOAD $uri, undef, content => "This is file content";
341 The name of the file sent to the server will simply be "b". Note that
343 in this case, you cannot pass other POST arguments to "UPLOAD()" --
344 they would be ignored.
345 UPLOAD_BODY
347 A shortcut function for "UPLOAD($uri, @params)->content".
349 UPLOAD_BODY_ASSERT
351 Use this function when your test is outputting content that you need to
353 check, and you want to make sure that the request was successful before
354 comparing the contents of the request. If the request was unsuccessful,
355 "UPLOAD_BODY_ASSERT" will return an error message. Otherwise it will
356 simply return the content of the request just as "UPLOAD_BODY" would.
357 OPTIONS
359 my $res = OPTIONS $uri;
361 Sends an "OPTIONS" request to the Apache test server. Returns an
363 "HTTP::Response" object with the Allow header, indicating which methods
364 the server supports. Possible methods include "OPTIONS", "GET", "HEAD"
365 and "POST". This function thus can be useful for testing what options
366 the Apache server supports. Consult the HTTPD 1.1 specification,
367 section 9.2, at http://www.faqs.org/rfcs/rfc2616.html for more
368 information.
369 URL Manipulation Functions
371 "Apache::TestRequest" also includes a few helper functions to aid in
372 the creation of urls used in the functions above.
373 "module2path"
375 $path = Apache::TestRequest::module2path($module_name);
377 Convert a module name to a path, safe for use in the various request
379 methods above. e.g. "::" can't be used in URLs on win32. For example:
380 $path = Apache::TestRequest::module2path('Foo::Bar');
382 returns:
384 /Foo__Bar
386 "module2url"
388 $url = Apache::TestRequest::module2url($module);
390 $url = Apache::TestRequest::module2url($module, \%options);
391 Convert a module name to a full URL including the current
393 configurations "hostname:port" and sets "module" accordingly.
394 $url = Apache::TestRequest::module2url('Foo::Bar');
396 returns:
398 http://$hostname:$port/Foo__Bar
400 The default scheme used is "http". You can override this by passing
402 your preferred scheme into an optional second param. For example:
403 $module = 'MyTestModule::TestHandler';
405 $url = Apache::TestRequest::module2url($module, {scheme => 'https'});
406 returns:
408 https://$hostname:$port/MyTestModule__TestHandler
410 You may also override the default path with a path of your own:
412 $module = 'MyTestModule::TestHandler';
414 $url = Apache::TestRequest::module2url($module, {path => '/foo'});
415 returns:
417 http://$hostname:$port/foo
419
421 The following environment variables can affect the behavior of
422 "Apache::TestRequest":
423 APACHE_TEST_PRETEND_NO_LWP
425 If the environment variable "APACHE_TEST_PRETEND_NO_LWP" is set to
426 a true value, "Apache::TestRequest" will pretend that LWP is not
427 available so one can test whether the test suite will survive on a
428 system which doesn't have libwww-perl installed.
429 APACHE_TEST_HTTP_09_OK
431 If the environment variable "APACHE_TEST_HTTP_09_OK" is set to a
432 true value, "Apache::TestRequest" will allow HTTP/0.9 responses
433 from the server to proceed. The default behavior is to die if the
434 response protocol is not either HTTP/1.0 or HTTP/1.1.
435
437 Apache::Test is the main Apache testing module. Use it to set up your
438 tests, create a plan, and to ensure that you have the Apache version
439 and modules you need.
440 Use Apache::TestMM in your Makefile.PL to set up your distribution for
442 testing.
443
445 Doug MacEachern with contributions from Geoffrey Young, Philippe M.
446 Chiasson, Stas Bekman and others. Documentation by David Wheeler.
447 Questions can be asked at the test-dev <at> httpd.apache.org list. For
449 more information see: http://httpd.apache.org/test/ and
450 http://perl.apache.org/docs/general/testing/testing.html.
451perl v5.36.0 2022-07-21 Apache::TestRequest(3)