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

Additional Configuration Variables

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

Test::More Integration

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

Apache::TestToString Class

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

AUTHOR

414       Doug MacEachern with contributions from Geoffrey Young, Philippe M.
415       Chiasson, Stas Bekman and others.
416
417       Questions can be asked at the test-dev <at> httpd.apache.org list For
418       more information see: http://httpd.apache.org/test/.
419
420
421
422perl v5.8.8                       2006-11-19                   Apache::Test(3)