Apache::Test(3pm)

1Apache::Test(3)       User Contributed Perl Documentation      Apache::Test(3)
2
3
4

NAME

6       Apache::Test - Test.pm wrapper with helpers for testing Apache
7

SYNOPSIS

9           use Apache::Test;
10

DESCRIPTION

12       Apache::Test is a wrapper around the standard "Test.pm" with helpers
13       for testing an Apache server.
14

FUNCTIONS

16       plan
17           This function is a wrapper around "Test::plan":
18
19               plan tests => 3;
20
21           just like using Test.pm, plan 3 tests.
22
23           If the first argument is an object, such as an "Apache::RequestRec"
24           object, "STDOUT" will be tied to it. The "Test.pm" global state
25           will also be refreshed by calling "Apache::Test::test_pm_refresh".
26           For example:
27
28               plan $r, tests => 7;
29
30           ties STDOUT to the request object $r.
31
32           If there is a last argument that doesn't belong to "Test::plan"
33           (which expects a balanced hash), it's used to decide whether to
34           continue with the test or to skip it all-together. This last
35           argument can be:
36
37           ·   a "SCALAR"
38
39               the test is skipped if the scalar has a false value. For
40               example:
41
42                 plan tests => 5, 0;
43
44               But this won't hint the reason for skipping therefore it's
45               better to use need():
46
47                 plan tests => 5,
48                     need 'LWP',
49                          { "not Win32" => sub { $^O eq 'MSWin32'} };
50
51               see "need()" for more info.
52
53           ·   an "ARRAY" reference
54
55               need_module() is called for each value in this array. The test
56               is skipped if need_module() returns false (which happens when
57               at least one C or Perl module from the list cannot be found).
58
59               Watch out for case insensitive file systems or duplicate
60               modules with the same name.  I.E.  If you mean mod_env.c
61                  need_module('mod_env.c') Not
62                  need_module('env')
63
64           ·   a "CODE" reference
65
66               the tests will be skipped if the function returns a false
67               value. For example:
68
69                   plan tests => 5, need_lwp;
70
71               the test will be skipped if LWP is not available
72
73           All other arguments are passed through to Test::plan as is.
74
75       ok  Same as Test::ok, see Test.pm documentation.
76
77       sok Allows to skip a sub-test, controlled from the command line.  The
78           argument to sok() is a CODE reference or a BLOCK whose return value
79           will be passed to ok(). By default behaves like ok(). If all sub-
80           tests of the same test are written using sok(), and a test is
81           executed as:
82
83             % ./t/TEST -v skip_subtest 1 3
84
85           only sub-tests 1 and 3 will be run, the rest will be skipped.
86
87       skip
88           Same as Test::skip, see Test.pm documentation.
89
90       test_pm_refresh
91           Normally called by Apache::Test::plan, this function will refresh
92           the global state maintained by Test.pm, allowing "plan" and friends
93           to be called more than once per-process.  This function is not
94           exported.
95
96       Functions that can be used as a last argument to the extended plan().
97       Note that for each "need_*" function there is a "have_*" equivalent
98       that performs the exact same function except that it is designed to be
99       used outside of "plan()".  "need_*" functions have the side effect of
100       generating skip messages, if the test is skipped.  "have_*" functions
101       don't have this side effect.  In other words, use "need_apache()" with
102       "plan()" to decide whether a test will run, but "have_apache()" within
103       test logic to adjust expectations based on older or newer server
104       versions.
105
106       need_http11
107             plan tests => 5, need_http11;
108
109           Require HTTP/1.1 support.
110
111       need_ssl
112             plan tests => 5, need_ssl;
113
114           Require SSL support.
115
116           Not exported by default.
117
118       need_lwp
119             plan tests => 5, need_lwp;
120
121           Require LWP support.
122
123       need_cgi
124             plan tests => 5, need_cgi;
125
126           Requires mod_cgi or mod_cgid to be installed.
127
128       need_php
129             plan tests => 5, need_php;
130
131           Requires a PHP module to be installed (version 4 or 5).
132
133       need_php4
134             plan tests => 5, need_php4;
135
136           Requires a PHP version 4 module to be installed.
137
138       need_imagemap
139             plan tests => 5, need_imagemap;
140
141           Requires a mod_imagemap or mod_imap be installed
142
143       need_apache
144             plan tests => 5, need_apache 2;
145
146           Requires Apache 2nd generation httpd-2.x.xx
147
148             plan tests => 5, need_apache 1;
149
150           Requires Apache 1st generation (apache-1.3.xx)
151
152           See also "need_min_apache_version()".
153
154       need_min_apache_version
155           Used to require a minimum version of Apache.
156
157           For example:
158
159             plan tests => 5, need_min_apache_version("2.0.40");
160
161           requires Apache 2.0.40 or higher.
162
163       need_apache_version
164           Used to require a specific version of Apache.
165
166           For example:
167
168             plan tests => 5, need_apache_version("2.0.40");
169
170           requires Apache 2.0.40.
171
172       need_apache_mpm
173           Used to require a specific Apache Multi-Processing Module.
174
175           For example:
176
177             plan tests => 5, need_apache_mpm('prefork');
178
179           requires the prefork MPM.
180
181       need_perl
182             plan tests => 5, need_perl 'iolayers';
183             plan tests => 5, need_perl 'ithreads';
184
185           Requires a perl extension to be present, or perl compiled with
186           certain capabilities.
187
188           The first example tests whether "PerlIO" is available, the second
189           whether:
190
191             $Config{useithread} eq 'define';
192
193       need_min_perl_version
194           Used to require a minimum version of Perl.
195
196           For example:
197
198             plan tests => 5, need_min_perl_version("5.008001");
199
200           requires Perl 5.8.1 or higher.
201
202       need_module
203             plan tests => 5, need_module 'CGI';
204             plan tests => 5, need_module qw(CGI Find::File);
205             plan tests => 5, need_module ['CGI', 'Find::File', 'cgid'];
206
207           Requires Apache C and Perl modules. The function accept a list of
208           arguments or a reference to a list.
209
210           In case of C modules, depending on how the module name was passed
211           it may pass through the following completions:
212
213           1 need_module 'proxy_http.c'
214               If there is the .c extension, the module name will be looked up
215               as is, i.e. 'proxy_http.c'.
216
217           2 need_module 'mod_cgi'
218               The .c extension will be appended before the lookup, turning it
219               into 'mod_cgi.c'.
220
221           3 need_module 'cgi'
222               The .c extension and mod_ prefix will be added before the
223               lookup, turning it into 'mod_cgi.c'.
224
225       need_min_module_version
226           Used to require a minimum version of a module
227
228           For example:
229
230             plan tests => 5, need_min_module_version(CGI => 2.81);
231
232           requires "CGI.pm" version 2.81 or higher.
233
234           Currently works only for perl modules.
235
236       need
237             plan tests => 5,
238                 need 'LWP',
239                      { "perl >= 5.8.0 and w/ithreads is required" =>
240                        ($Config{useperlio} && $] >= 5.008) },
241                      { "not Win32"                 => sub { $^O eq 'MSWin32' },
242                        "foo is disabled"           => \&is_foo_enabled,
243                      },
244                      'cgid';
245
246           need() is more generic function which can impose multiple
247           requirements at once. All requirements must be satisfied.
248
249           need()'s argument is a list of things to test. The list can include
250           scalars, which are passed to need_module(), and hash references. If
251           hash references are used, the keys, are strings, containing a
252           reason for a failure to satisfy this particular entry, the values
253           are the condition, which are satisfaction if they return true. If
254           the value is 0 or 1, it used to decide whether the requirements
255           very satisfied, so you can mix special "need_*()" functions that
256           return 0 or 1. For example:
257
258             plan tests => 1, need 'Compress::Zlib', 'deflate',
259                 need_min_apache_version("2.0.49");
260
261           If the scalar value is a string, different from 0 or 1, it's passed
262           to need_module().  If the value is a code reference, it gets
263           executed at the time of check and its return value is used to check
264           the condition. If the condition check fails, the provided (in a
265           key) reason is used to tell user why the test was skipped.
266
267           In the presented example, we require the presence of the "LWP" Perl
268           module, "mod_cgid", that we run under perl >= 5.7.3 on Win32.
269
270           It's possible to put more than one requirement into a single hash
271           reference, but be careful that the keys will be different.
272
273           It's also important to mention to avoid using:
274
275             plan tests => 1, requirement1 && requirement2;
276
277           technique. While test-wise that technique is equivalent to:
278
279             plan tests => 1, need requirement1, requirement2;
280
281           since the test will be skipped, unless all the rules are satisfied,
282           it's not equivalent for the end users. The second technique,
283           deploying "need()" and a list of requirements, always runs all the
284           requirement checks and reports all the missing requirements. In the
285           case of the first technique, if the first requirement fails, the
286           second is not run, and the missing requirement is not reported. So
287           let's say all the requirements are missing Apache modules, and a
288           user wants to satisfy all of these and run the test suite again. If
289           all the unsatisfied requirements are reported at once, she will
290           need to rebuild Apache once. If only one requirement is reported at
291           a time, she will have to rebuild Apache as many times as there are
292           elements in the "&&" statement.
293
294           Also see plan().
295
296       under_construction
297             plan tests => 5, under_construction;
298
299           skip all tests, noting that the tests are under construction
300
301       skip_reason
302             plan tests => 5, skip_reason('my custom reason');
303
304           skip all tests.  the reason you specify will be given at runtime.
305           if no reason is given a default reason will be used.
306

Additional Configuration Variables

308       basic_config
309             my $basic_cfg = Apache::Test::basic_config();
310             $basic_cfg->write_perlscript($file, $content);
311
312           "basic_config()" is similar to "config()", but doesn't contain any
313           httpd-specific information and should be used for operations that
314           don't require any httpd-specific knowledge.
315
316       config
317             my $cfg = Apache::Test::config();
318             my $server_rev = $cfg->{server}->{rev};
319             ...
320
321           "config()" gives an access to the configuration object.
322
323       vars
324             my $serverroot = Apache::Test::vars->{serverroot};
325             my $serverroot = Apache::Test::vars('serverroot');
326             my($top_dir, $t_dir) = Apache::Test::vars(qw(top_dir t_dir));
327
328           "vars()" gives an access to the configuration variables, otherwise
329           accessible as:
330
331             $vars = Apache::Test::config()->{vars};
332
333           If no arguments are passed, the reference to the variables hash is
334           returned. If one or more arguments are passed the corresponding
335           values are returned.
336

Test::More Integration

338       There are a few caveats if you want to use Apache::Test with Test::More
339       instead of the default Test backend.  The first is that Test::More
340       requires you to use its own "plan()" function and not the one that
341       ships with Apache::Test.  Test::More also defines "ok()" and "skip()"
342       functions that are different, and simply "use"ing both modules in your
343       test script will lead to redefined warnings for these subroutines.
344
345       To assist Test::More users we have created a special Apache::Test
346       import tag, ":withtestmore", which will export all of the standard
347       Apache::Test symbols into your namespace except the ones that collide
348       with Test::More.
349
350           use Apache::Test qw(:withtestmore);
351           use Test::More;
352
353           plan tests => 1;           # Test::More::plan()
354
355           ok ('yes', 'testing ok');  # Test::More::ok()
356
357       Now, while this works fine for standard client-side tests (such as
358       "t/basic.t"), the more advanced features of Apache::Test require using
359       Test::More as the sole driver behind the scenes.
360
361       Should you choose to use Test::More as the backend for server-based
362       tests (such as "t/response/TestMe/basic.pm") you will need to use the
363       "-withtestmore" action tag:
364
365           use Apache::Test qw(-withtestmore);
366
367           sub handler {
368
369               my $r = shift;
370
371               plan $r, tests => 1;           # Test::More::plan() with
372                                              # Apache::Test features
373
374               ok ('yes', 'testing ok');      # Test::More::ok()
375           }
376
377       "-withtestmore" tells Apache::Test to use Test::More instead of Test.pm
378       behind the scenes.  Note that you are not required to "use Test::More"
379       yourself with the "-withtestmore" option and that the "use Test::More
380       tests => 1" syntax may have unexpected results.
381
382       Note that Test::More version 0.49, available within the Test::Simple
383       0.49 distribution on CPAN, or greater is required to use this feature.
384
385       Because Apache:Test was initially developed using Test as the framework
386       driver, complete Test::More integration is considered experimental at
387       this time - it is supported as best as possible but is not guaranteed
388       to be as stable as the default Test interface at this time.
389

Apache::TestToString Class

391       The Apache::TestToString class is used to capture Test.pm output into a
392       string.  Example:
393
394           Apache::TestToString->start;
395
396           plan tests => 4;
397
398           ok $data eq 'foo';
399
400           ...
401
402           # $tests will contain the Test.pm output: 1..4\nok 1\n...
403           my $tests = Apache::TestToString->finish;
404

AUTHOR

417       Doug MacEachern with contributions from Geoffrey Young, Philippe M.
418       Chiasson, Stas Bekman and others.
419
420       Questions can be asked at the test-dev <at> httpd.apache.org list For
421       more information see: http://httpd.apache.org/test/.
422

POD ERRORS

424       Hey! The above document had some coding errors, which are explained
425       below:
426
427       Around line 939:
428           '=item' outside of any '=over'
429
430       Around line 971:
431           You forgot a '=back' before '=head1'
432
433
434
435perl v5.10.1                      2007-12-31                   Apache::Test(3)