Apache::TestRequest(3pm)

1Apache::TestRequest(3)User Contributed Perl DocumentationApache::TestRequest(3)
2
3
4

NAME

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

SYNOPSIS

9         use Apache::Test qw(ok have_lwp);
10         use Apache::TestRequest qw(GET POST);
11         use Apache::Constants qw(HTTP_OK);
12
13         plan tests => 1, have_lwp;
14
15         my $res = GET '/test.html';
16         ok $res->code == HTTP_OK, "Request is ok";
17

DESCRIPTION

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
27       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
35         use Apache::Test qw(ok have_lwp);
36         use Apache::TestRequest qw(GET POST);
37         use Apache::Constants qw(HTTP_OK);
38
39         plan tests => 2, have_lwp;
40
41         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
46       Note that you can also use "Apache::TestRequest" with "Test::Builder"
47       and its derivatives, including "Test::More":
48
49         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

CONFIGURATION FUNCTION

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 conve‐
59       nience 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
63       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
68         Apache::TestRequest::user_agent(reset => 1, %params);
69
70       "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" docu‐
74       mentation, has the effect of loading and enabling the new experimental
75       HTTP/1.1 protocol module).
76
77       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
83         Apache::TestRequest::user_agent(reset => 1,
84                                         requests_redirectable => 0);
85
86       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
91         # 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
96       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
100       Sometimes it is desireable to have "Apache::TestRequest" remember cook‐
101       ies sent by the pages you are testing and send them back to the server
102       on subsequent requests. This is especially necessary when testing pages
103       whose functionality relies on sessions or the presence of preferences
104       stored in cookies.
105
106       By default, "LWP::UserAgent" does not remember cookies between
107       requests. You can tell it to remember cookies between request by
108       adding:
109
110         Apache::TestRequest::user_agent(cookie_jar => {});
111
112       before issuing the requests.
113

FUNCTIONS

115       "Apache::TestRequest" exports a number of functions that will likely
116       prove convenient for use in the majority of your request tests.
117
118       Optional Parameters
119
120       Each function also takes a number of optional arguments.
121
122       redirect_ok
123           By default a request will follow redirects retrieved from the
124           server. To prevent this behavior, pass a false value to a "redi‐
125           rect_ok" parameter:
126
127             my $res = GET $uri, redirect_ok => 0;
128
129           Alternately, if all of your tests need to disable redirects, tell
130           "Apache::TestRequest" to use an "LWP::UserAgent" object that dis‐
131           ables redirects:
132
133             Apache::TestRequest::user_agent( reset => 1,
134                                              requests_redirectable => 0 );
135
136       cert
137           If you need to force an SSL request to use a particular SSL cer‐
138           tificate, pass the name of the certificate via the "cert" parame‐
139           ter:
140
141             my $res = GET $uri, cert => 'my_cert';
142
143       content
144           If you need to add content to your request, use the "content"
145           parameter:
146
147             my $res = GET $uri, content => 'hello world!';
148
149       filename
150           The name of a local file on the file system to be sent to the
151           Apache test server via "UPLOAD()" and its friends.
152
153       The Functions
154
155       GET
156
157         my $res = GET $uri;
158
159       Sends a simple GET request to the Apache test server. Returns an
160       "HTTP::Response" object.
161
162       You can also supply additional headers to be sent with the request by
163       adding their name/value pairs after the "url" parameter, for example:
164
165         my $res = GET $url, 'Accept-Language' => 'de,en-us,en;q=0.5';
166
167       GET_STR
168
169       A shortcut function for "GET($uri)->as_string".
170
171       GET_BODY
172
173       A shortcut function for "GET($uri)->content".
174
175       GET_BODY_ASSERT
176
177       Use this function when your test is outputting content that you need to
178       check, and you want to make sure that the request was successful before
179       comparing the contents of the request. If the request was unsuccessful,
180       "GET_BODY_ASSERT" will return an error message. Otherwise it will sim‐
181       ply return the content of the request just as "GET_BODY" would.
182
183       GET_OK
184
185       A shortcut function for "GET($uri)->is_success".
186
187       GET_RC
188
189       A shortcut function for "GET($uri)->code".
190
191       GET_HEAD
192
193       Throws out the content of the request, and returns the string represen‐
194       tation of the request. Since the body has been thrown out, the repre‐
195       sentation will consist solely of the headers. Furthermore, "GET_HEAD"
196       inserts a "#" at the beginning of each line of the return string, so
197       that the contents are suitable for printing to STDERR during your tests
198       without interfering with the workings of "Test::Harness".
199
200       HEAD
201
202         my $res = HEAD $uri;
203
204       Sends a HEAD request to the Apache test server. Returns an
205       "HTTP::Response" object.
206
207       HEAD_STR
208
209       A shortcut function for "HEAD($uri)->as_string".
210
211       HEAD_BODY
212
213       A shortcut function for "HEAD($uri)->content". Of course, this means
214       that it will likely return nothing.
215
216       HEAD_BODY_ASSERT
217
218       Use this function when your test is outputting content that you need to
219       check, and you want to make sure that the request was successful before
220       comparing the contents of the request. If the request was unsuccessful,
221       "HEAD_BODY_ASSERT" will return an error message. Otherwise it will sim‐
222       ply return the content of the request just as "HEAD_BODY" would.
223
224       HEAD_OK
225
226       A shortcut function for "GET($uri)->is_success".
227
228       HEAD_RC
229
230       A shortcut function for "GET($uri)->code".
231
232       HEAD_HEAD
233
234       Throws out the content of the request, and returns the string represen‐
235       tation of the request. Since the body has been thrown out, the repre‐
236       sentation will consist solely of the headers. Furthermore, "GET_HEAD"
237       inserts a "#" at the beginning of each line of the return string, so
238       that the contents are suitable for printing to STDERR during your tests
239       without interfering with the workings of "Test::Harness".
240
241       PUT
242
243         my $res = PUT $uri;
244
245       Sends a simple PUT request to the Apache test server. Returns an
246       "HTTP::Response" object.
247
248       PUT_STR
249
250       A shortcut function for "PUT($uri)->as_string".
251
252       PUT_BODY
253
254       A shortcut function for "PUT($uri)->content".
255
256       PUT_BODY_ASSERT
257
258       Use this function when your test is outputting content that you need to
259       check, and you want to make sure that the request was successful before
260       comparing the contents of the request. If the request was unsuccessful,
261       "PUT_BODY_ASSERT" will return an error message. Otherwise it will sim‐
262       ply return the content of the request just as "PUT_BODY" would.
263
264       PUT_OK
265
266       A shortcut function for "PUT($uri)->is_success".
267
268       PUT_RC
269
270       A shortcut function for "PUT($uri)->code".
271
272       PUT_HEAD
273
274       Throws out the content of the request, and returns the string represen‐
275       tation of the request. Since the body has been thrown out, the repre‐
276       sentation will consist solely of the headers. Furthermore, "PUT_HEAD"
277       inserts a "#" at the beginning of each line of the return string, so
278       that the contents are suitable for printing to STDERR during your tests
279       without interfering with the workings of "Test::Harness".
280
281       POST
282
283         my $res = POST $uri, [ arg => $val, arg2 => $val ];
284
285       Sends a POST request to the Apache test server and returns an
286       "HTTP::Response" object. An array reference of parameters passed as the
287       second argument will be submitted to the Apache test server as the POST
288       content. Parameters corresponding to those documented in Optional
289       Parameters can follow the optional array reference of parameters, or
290       after $uri.
291
292       To upload a chunk of data, simply use:
293
294         my $res = POST $uri, content => $data;
295
296       POST_STR
297
298       A shortcut function for "POST($uri, @args)->content".
299
300       POST_BODY
301
302       A shortcut function for "POST($uri, @args)->content".
303
304       POST_BODY_ASSERT
305
306       Use this function when your test is outputting content that you need to
307       check, and you want to make sure that the request was successful before
308       comparing the contents of the request. If the request was unsuccessful,
309       "POST_BODY_ASSERT" will return an error message. Otherwise it will sim‐
310       ply return the content of the request just as "POST_BODY" would.
311
312       POST_OK
313
314       A shortcut function for "POST($uri, @args)->is_success".
315
316       POST_RC
317
318       A shortcut function for "POST($uri, @args)->code".
319
320       POST_HEAD
321
322       Throws out the content of the request, and returns the string represen‐
323       tation of the request. Since the body has been thrown out, the repre‐
324       sentation will consist solely of the headers. Furthermore, "POST_HEAD"
325       inserts a "#" at the beginning of each line of the return string, so
326       that the contents are suitable for printing to STDERR during your tests
327       without interfering with the workings of "Test::Harness".
328
329       UPLOAD
330
331         my $res = UPLOAD $uri, \@args, filename => $filename;
332
333       Sends a request to the Apache test server that includes an uploaded
334       file. Other POST parameters can be passed as a second argument as an
335       array reference.
336
337       "Apache::TestRequest" will read in the contents of the file named via
338       the "filename" parameter for submission to the server. If you'd rather,
339       you can submit use the "content" parameter instead of "filename", and
340       its value will be submitted to the Apache server as file contents:
341
342         my $res = UPLOAD $uri, undef, content => "This is file content";
343
344       The name of the file sent to the server will simply be "b". Note that
345       in this case, you cannot pass other POST arguments to "UPLOAD()" --
346       they would be ignored.
347
348       UPLOAD_BODY
349
350       A shortcut function for "UPLOAD($uri, @params)->content".
351
352       UPLOAD_BODY_ASSERT
353
354       Use this function when your test is outputting content that you need to
355       check, and you want to make sure that the request was successful before
356       comparing the contents of the request. If the request was unsuccessful,
357       "UPLOAD_BODY_ASSERT" will return an error message. Otherwise it will
358       simply return the content of the request just as "UPLOAD_BODY" would.
359
360       OPTIONS
361
362         my $res = OPTIONS $uri;
363
364       Sends an "OPTIONS" request to the Apache test server. Returns an
365       "HTTP::Response" object with the Allow header, indicating which methods
366       the server supports. Possible methods include "OPTIONS", "GET", "HEAD"
367       and "POST". This function thus can be useful for testing what options
368       the Apache server supports. Consult the HTTPD 1.1 specification, sec‐
369       tion 9.2, at http://www.faqs.org/rfcs/rfc2616.html for more informa‐
370       tion.
371
372       URL Manipulation Functions
373
374       "Apache::TestRequest" also includes a few helper functions to aid in
375       the creation of urls used in the functions above.
376
377       "module2path"
378
379         $path = Apache::TestRequest::module2path($module_name);
380
381       Convert a module name to a path, safe for use in the various request
382       methods above. e.g. "::" can't be used in URLs on win32. For example:
383
384         $path = Apache::TestRequest::module2path('Foo::Bar');
385
386       returns:
387
388         /Foo__Bar
389
390       "module2url"
391
392         $url = Apache::TestRequest::module2url($module);
393         $url = Apache::TestRequest::module2url($module, \%options);
394
395       Convert a module name to a full URL including the current configura‐
396       tions "hostname:port" and sets "module" accordingly.
397
398         $url = Apache::TestRequest::module2url('Foo::Bar');
399
400       returns:
401
402         http://$hostname:$port/Foo__Bar
403
404       The default scheme used is "http". You can override this by passing
405       your preferred scheme into an optional second param. For example:
406
407         $module = 'MyTestModule::TestHandler';
408         $url = Apache::TestRequest::module2url($module, {scheme => 'https'});
409
410       returns:
411
412         https://$hostname:$port/MyTestModule__TestHandler
413
414       You may also override the default path with a path of your own:
415
416         $module = 'MyTestModule::TestHandler';
417         $url = Apache::TestRequest::module2url($module, {path => '/foo'});
418
419       returns:
420
421         http://$hostname:$port/foo
422

ENVIRONMENT VARIABLES

424       The following environment variables can affect the behavior of
425       "Apache::TestRequest":
426
427       APACHE_TEST_PRETEND_NO_LWP
428           If the environment variable "APACHE_TEST_PRETEND_NO_LWP" is set to
429           a true value, "Apache::TestRequest" will pretend that LWP is not
430           available so one can test whether the test suite will survive on a
431           system which doesn't have libwww-perl installed.
432
433       APACHE_TEST_HTTP_09_OK
434           If the environment variable "APACHE_TEST_HTTP_09_OK" is set to a
435           true value, "Apache::TestRequest" will allow HTTP/0.9 responses
436           from the server to proceed.  The default behavior is to die if the
437           response protocol is not either HTTP/1.0 or HTTP/1.1.
438

AUTHOR

448       Doug MacEachern with contributions from Geoffrey Young, Philippe M.
449       Chiasson, Stas Bekman and others. Documentation by David Wheeler.
450
451       Questions can be asked at the test-dev <at> httpd.apache.org list. For
452       more information see: http://httpd.apache.org/test/ and
453       http://perl.apache.org/docs/general/testing/testing.html.
454
455
456
457perl v5.8.8                       2006-11-19            Apache::TestRequest(3)