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

Additional Configuration Variables

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

Test::More Integration

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

Apache::TestToString Class

399       The Apache::TestToString class is used to capture Test.pm output into a
400       string.  Example:
401
402           Apache::TestToString->start;
403
404           plan tests => 4;
405
406           ok $data eq 'foo';
407
408           ...
409
410           # $tests will contain the Test.pm output: 1..4\nok 1\n...
411           my $tests = Apache::TestToString->finish;
412

AUTHOR

425       Doug MacEachern with contributions from Geoffrey Young, Philippe M.
426       Chiasson, Stas Bekman and others.
427
428       Questions can be asked at the test-dev <at> httpd.apache.org list For
429       more information see: http://httpd.apache.org/test/.
430
431
432
433perl v5.28.0                      2016-10-27                   Apache::Test(3)