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

Additional Configuration Variables

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

Test::More Integration

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

Apache::TestToString Class

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

AUTHOR

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