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_cache_disk
129             plan tests => 5, need_cache_disk
130
131           Requires mod_cache_disk or mod_disk_cache to be installed.
132
133       need_php
134             plan tests => 5, need_php;
135
136           Requires a PHP module to be installed (version 4 or 5).
137
138       need_php4
139             plan tests => 5, need_php4;
140
141           Requires a PHP version 4 module to be installed.
142
143       need_imagemap
144             plan tests => 5, need_imagemap;
145
146           Requires a mod_imagemap or mod_imap be installed
147
148       need_apache
149             plan tests => 5, need_apache 2;
150
151           Requires Apache 2nd generation httpd-2.x.xx
152
153             plan tests => 5, need_apache 1;
154
155           Requires Apache 1st generation (apache-1.3.xx)
156
157           See also "need_min_apache_version()".
158
159       need_min_apache_version
160           Used to require a minimum version of Apache.
161
162           For example:
163
164             plan tests => 5, need_min_apache_version("2.0.40");
165
166           requires Apache 2.0.40 or higher.
167
168       need_apache_version
169           Used to require a specific version of Apache.
170
171           For example:
172
173             plan tests => 5, need_apache_version("2.0.40");
174
175           requires Apache 2.0.40.
176
177       need_min_apache_fix
178           Used to require a particular micro version from corresponding minor
179           release
180
181           For example:
182
183             plan tests => 5, need_min_apache_fix("2.0.40", "2.2.30", "2.4.18");
184
185           requires Apache 2.0.40 or higher.
186
187       need_apache_mpm
188           Used to require a specific Apache Multi-Processing Module.
189
190           For example:
191
192             plan tests => 5, need_apache_mpm('prefork');
193
194           requires the prefork MPM.
195
196       need_perl
197             plan tests => 5, need_perl 'iolayers';
198             plan tests => 5, need_perl 'ithreads';
199
200           Requires a perl extension to be present, or perl compiled with
201           certain capabilities.
202
203           The first example tests whether "PerlIO" is available, the second
204           whether:
205
206             $Config{useithread} eq 'define';
207
208       need_min_perl_version
209           Used to require a minimum version of Perl.
210
211           For example:
212
213             plan tests => 5, need_min_perl_version("5.008001");
214
215           requires Perl 5.8.1 or higher.
216
217       need_fork
218           Requires the perl built-in function "fork" to be implemented.
219
220       need_module
221             plan tests => 5, need_module 'CGI';
222             plan tests => 5, need_module qw(CGI Find::File);
223             plan tests => 5, need_module ['CGI', 'Find::File', 'cgid'];
224
225           Requires Apache C and Perl modules. The function accept a list of
226           arguments or a reference to a list.
227
228           In case of C modules, depending on how the module name was passed
229           it may pass through the following completions:
230
231           1 need_module 'proxy_http.c'
232               If there is the .c extension, the module name will be looked up
233               as is, i.e. 'proxy_http.c'.
234
235           2 need_module 'mod_cgi'
236               The .c extension will be appended before the lookup, turning it
237               into 'mod_cgi.c'.
238
239           3 need_module 'cgi'
240               The .c extension and mod_ prefix will be added before the
241               lookup, turning it into 'mod_cgi.c'.
242
243       need_min_module_version
244           Used to require a minimum version of a module
245
246           For example:
247
248             plan tests => 5, need_min_module_version(CGI => 2.81);
249
250           requires "CGI.pm" version 2.81 or higher.
251
252           Currently works only for perl modules.
253
254       need
255             plan tests => 5,
256                 need 'LWP',
257                      { "perl >= 5.8.0 and w/ithreads is required" =>
258                        ($Config{useperlio} && $] >= 5.008) },
259                      { "not Win32"                 => sub { $^O eq 'MSWin32' },
260                        "foo is disabled"           => \&is_foo_enabled,
261                      },
262                      'cgid';
263
264           need() is more generic function which can impose multiple
265           requirements at once. All requirements must be satisfied.
266
267           need()'s argument is a list of things to test. The list can include
268           scalars, which are passed to need_module(), and hash references. If
269           hash references are used, the keys, are strings, containing a
270           reason for a failure to satisfy this particular entry, the values
271           are the condition, which are satisfaction if they return true. If
272           the value is 0 or 1, it used to decide whether the requirements
273           very satisfied, so you can mix special "need_*()" functions that
274           return 0 or 1. For example:
275
276             plan tests => 1, need 'Compress::Zlib', 'deflate',
277                 need_min_apache_version("2.0.49");
278
279           If the scalar value is a string, different from 0 or 1, it's passed
280           to need_module().  If the value is a code reference, it gets
281           executed at the time of check and its return value is used to check
282           the condition. If the condition check fails, the provided (in a
283           key) reason is used to tell user why the test was skipped.
284
285           In the presented example, we require the presence of the "LWP" Perl
286           module, "mod_cgid", that we run under perl >= 5.7.3 on Win32.
287
288           It's possible to put more than one requirement into a single hash
289           reference, but be careful that the keys will be different.
290
291           It's also important to mention to avoid using:
292
293             plan tests => 1, requirement1 && requirement2;
294
295           technique. While test-wise that technique is equivalent to:
296
297             plan tests => 1, need requirement1, requirement2;
298
299           since the test will be skipped, unless all the rules are satisfied,
300           it's not equivalent for the end users. The second technique,
301           deploying "need()" and a list of requirements, always runs all the
302           requirement checks and reports all the missing requirements. In the
303           case of the first technique, if the first requirement fails, the
304           second is not run, and the missing requirement is not reported. So
305           let's say all the requirements are missing Apache modules, and a
306           user wants to satisfy all of these and run the test suite again. If
307           all the unsatisfied requirements are reported at once, she will
308           need to rebuild Apache once. If only one requirement is reported at
309           a time, she will have to rebuild Apache as many times as there are
310           elements in the "&&" statement.
311
312           Also see plan().
313
314       under_construction
315             plan tests => 5, under_construction;
316
317           skip all tests, noting that the tests are under construction
318
319       skip_reason
320             plan tests => 5, skip_reason('my custom reason');
321
322           skip all tests.  the reason you specify will be given at runtime.
323           if no reason is given a default reason will be used.
324

Additional Configuration Variables

326       basic_config
327             my $basic_cfg = Apache::Test::basic_config();
328             $basic_cfg->write_perlscript($file, $content);
329
330           "basic_config()" is similar to "config()", but doesn't contain any
331           httpd-specific information and should be used for operations that
332           don't require any httpd-specific knowledge.
333
334       config
335             my $cfg = Apache::Test::config();
336             my $server_rev = $cfg->{server}->{rev};
337             ...
338
339           "config()" gives an access to the configuration object.
340
341       vars
342             my $serverroot = Apache::Test::vars->{serverroot};
343             my $serverroot = Apache::Test::vars('serverroot');
344             my($top_dir, $t_dir) = Apache::Test::vars(qw(top_dir t_dir));
345
346           "vars()" gives an access to the configuration variables, otherwise
347           accessible as:
348
349             $vars = Apache::Test::config()->{vars};
350
351           If no arguments are passed, the reference to the variables hash is
352           returned. If one or more arguments are passed the corresponding
353           values are returned.
354

Test::More Integration

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

Apache::TestToString Class

409       The Apache::TestToString class is used to capture Test.pm output into a
410       string.  Example:
411
412           Apache::TestToString->start;
413
414           plan tests => 4;
415
416           ok $data eq 'foo';
417
418           ...
419
420           # $tests will contain the Test.pm output: 1..4\nok 1\n...
421           my $tests = Apache::TestToString->finish;
422

AUTHOR

435       Doug MacEachern with contributions from Geoffrey Young, Philippe M.
436       Chiasson, Stas Bekman and others.
437
438       Questions can be asked at the test-dev <at> httpd.apache.org list For
439       more information see: http://httpd.apache.org/test/.
440
441
442
443perl v5.32.0                      2020-07-28                   Apache::Test(3)