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
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
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 ways.
71       First, it supports an additional parameter, "keep_alive", which enables
72       connection persistence, where the same connection is used to process
73       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
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
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
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       Each function also takes a number of optional arguments.
120
121       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
126             my $res = GET $uri, redirect_ok => 0;
127
128           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
132             Apache::TestRequest::user_agent( reset => 1,
133                                              requests_redirectable => 0 );
134
135       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
140             my $res = GET $uri, cert => 'my_cert';
141
142       content
143           If you need to add content to your request, use the "content"
144           parameter:
145
146             my $res = GET $uri, content => 'hello world!';
147
148       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
152   The Functions
153       GET
154
155         my $res = GET $uri;
156
157       Sends a simple GET request to the Apache test server. Returns an
158       "HTTP::Response" object.
159
160       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
163         my $res = GET $url, 'Accept-Language' => 'de,en-us,en;q=0.5';
164
165       GET_STR
166
167       A shortcut function for "GET($uri)->as_string".
168
169       GET_BODY
170
171       A shortcut function for "GET($uri)->content".
172
173       GET_BODY_ASSERT
174
175       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
181       GET_OK
182
183       A shortcut function for "GET($uri)->is_success".
184
185       GET_RC
186
187       A shortcut function for "GET($uri)->code".
188
189       GET_HEAD
190
191       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
198       HEAD
199
200         my $res = HEAD $uri;
201
202       Sends a HEAD request to the Apache test server. Returns an
203       "HTTP::Response" object.
204
205       HEAD_STR
206
207       A shortcut function for "HEAD($uri)->as_string".
208
209       HEAD_BODY
210
211       A shortcut function for "HEAD($uri)->content". Of course, this means
212       that it will likely return nothing.
213
214       HEAD_BODY_ASSERT
215
216       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
222       HEAD_OK
223
224       A shortcut function for "GET($uri)->is_success".
225
226       HEAD_RC
227
228       A shortcut function for "GET($uri)->code".
229
230       HEAD_HEAD
231
232       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
239       PUT
240
241         my $res = PUT $uri;
242
243       Sends a simple PUT request to the Apache test server. Returns an
244       "HTTP::Response" object.
245
246       PUT_STR
247
248       A shortcut function for "PUT($uri)->as_string".
249
250       PUT_BODY
251
252       A shortcut function for "PUT($uri)->content".
253
254       PUT_BODY_ASSERT
255
256       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
262       PUT_OK
263
264       A shortcut function for "PUT($uri)->is_success".
265
266       PUT_RC
267
268       A shortcut function for "PUT($uri)->code".
269
270       PUT_HEAD
271
272       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
279       POST
280
281         my $res = POST $uri, [ arg => $val, arg2 => $val ];
282
283       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
290       To upload a chunk of data, simply use:
291
292         my $res = POST $uri, content => $data;
293
294       POST_STR
295
296       A shortcut function for "POST($uri, @args)->content".
297
298       POST_BODY
299
300       A shortcut function for "POST($uri, @args)->content".
301
302       POST_BODY_ASSERT
303
304       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
310       POST_OK
311
312       A shortcut function for "POST($uri, @args)->is_success".
313
314       POST_RC
315
316       A shortcut function for "POST($uri, @args)->code".
317
318       POST_HEAD
319
320       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
327       UPLOAD
328
329         my $res = UPLOAD $uri, \@args, filename => $filename;
330
331       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
335       "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
340         my $res = UPLOAD $uri, undef, content => "This is file content";
341
342       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() -- they
344       would be ignored.
345
346       UPLOAD_BODY
347
348       A shortcut function for "UPLOAD($uri, @params)->content".
349
350       UPLOAD_BODY_ASSERT
351
352       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
358       OPTIONS
359
360         my $res = OPTIONS $uri;
361
362       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
370   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
374       "module2path"
375
376         $path = Apache::TestRequest::module2path($module_name);
377
378       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
381         $path = Apache::TestRequest::module2path('Foo::Bar');
382
383       returns:
384
385         /Foo__Bar
386
387       "module2url"
388
389         $url = Apache::TestRequest::module2url($module);
390         $url = Apache::TestRequest::module2url($module, \%options);
391
392       Convert a module name to a full URL including the current
393       configurations "hostname:port" and sets "module" accordingly.
394
395         $url = Apache::TestRequest::module2url('Foo::Bar');
396
397       returns:
398
399         http://$hostname:$port/Foo__Bar
400
401       The default scheme used is "http". You can override this by passing
402       your preferred scheme into an optional second param. For example:
403
404         $module = 'MyTestModule::TestHandler';
405         $url = Apache::TestRequest::module2url($module, {scheme => 'https'});
406
407       returns:
408
409         https://$hostname:$port/MyTestModule__TestHandler
410
411       You may also override the default path with a path of your own:
412
413         $module = 'MyTestModule::TestHandler';
414         $url = Apache::TestRequest::module2url($module, {path => '/foo'});
415
416       returns:
417
418         http://$hostname:$port/foo
419

ENVIRONMENT VARIABLES

421       The following environment variables can affect the behavior of
422       "Apache::TestRequest":
423
424       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
430       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

AUTHOR

445       Doug MacEachern with contributions from Geoffrey Young, Philippe M.
446       Chiasson, Stas Bekman and others. Documentation by David Wheeler.
447
448       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.
451
452
453
454perl v5.36.0                      2023-01-19            Apache::TestRequest(3)