File Coverage

blib/lib/Apache/Test.pm
Criterion Covered Total %
statement 97 249 39.0
branch 34 106 32.1
condition 6 30 20.0
subroutine 21 49 42.9
pod 24 31 77.4
total 182 465 39.1


line stmt bran cond sub pod time code
1             # Licensed to the Apache Software Foundation (ASF) under one or more
2             # contributor license agreements. See the NOTICE file distributed with
3             # this work for additional information regarding copyright ownership.
4             # The ASF licenses this file to You under the Apache License, Version 2.0
5             # (the "License"); you may not use this file except in compliance with
6             # the License. You may obtain a copy of the License at
7             #
8             # http://www.apache.org/licenses/LICENSE-2.0
9             #
10             # Unless required by applicable law or agreed to in writing, software
11             # distributed under the License is distributed on an "AS IS" BASIS,
12             # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13             # See the License for the specific language governing permissions and
14             # limitations under the License.
15             #
16             package Apache::Test;
17              
18 6     6   83 use strict;
  6         54  
  6         88  
19 6     6   93 use warnings FATAL => 'all';
  6         53  
  6         78  
20              
21 6     6   162 use Exporter ();
  6         2257  
  6         58  
22 6     6   131 use Config;
  6         54  
  6         84  
23 6     6   140 use Apache::TestConfig ();
  6         61  
  6         63  
24              
25             BEGIN {
26             # Apache::Test loads a bunch of mp2 stuff while getting itself
27             # together. because we need to choose one of mp1 or mp2 to load
28             # check first (and we choose mp2) $mod_perl::VERSION == 2.0
29             # just because someone loaded Apache::Test. This Is Bad. so,
30             # let's try to correct for that here by removing mod_perl from
31             # %INC after the above use() statements settle in. nobody
32             # should be relying on us loading up mod_perl.pm anyway...
33              
34 6     6   112     delete $INC{'mod_perl.pm'};
35             }
36              
37 6     6   554 use vars qw(@ISA @EXPORT %EXPORT_TAGS $VERSION %SubTests @SkipReasons);
  6         65  
  6         119  
38              
39             $VERSION = '1.29';
40              
41             my @need = qw(need_lwp need_http11 need_cgi need_access need_auth
42             need_module need_apache need_min_apache_version
43             need_apache_version need_perl need_min_perl_version
44             need_min_module_version need_threads need_apache_mpm
45             need_php need_php4 need_ssl need_imagemap);
46              
47             my @have = map { (my $need = $_) =~ s/need/have/; $need } @need;
48              
49             @ISA = qw(Exporter);
50             @EXPORT = (qw(ok skip sok plan skip_reason under_construction need),
51                        @need, @have);
52              
53             # everything but ok(), skip(), and plan() - Test::More provides these
54             my @test_more_exports = grep { ! /^(ok|skip|plan)$/ } @EXPORT;
55              
56             %EXPORT_TAGS = (withtestmore => \@test_more_exports);
57              
58             %SubTests = ();
59             @SkipReasons = ();
60              
61             if (my $subtests = $ENV{HTTPD_TEST_SUBTESTS}) {
62                 %SubTests = map { $_, 1 } split /\s+/, $subtests;
63             }
64              
65             my $Config;
66             my $real_plan;
67             my @testmore;
68              
69             sub import {
70 6     6   69     my $class = shift;
71              
72             # once Test::More always Test::More until plan() is called
73 6 50 33     327     if (($_[0] and $_[0] =~ m/^-withtestmore/) || @testmore) {
      33        
74             # special hoops for Test::More support
75              
76 0 0       0         $real_plan = eval {
77              
78 0         0             require Test::More;
79              
80 6     6   121             no warnings qw(numeric);
  6         57  
  6         161  
81 0         0             Test::Builder->VERSION('0.18_01');
82              
83             # required for Test::More::import() and Apache::Test::plan()
84             # if we don't do this, Test::More exports plan() anyway
85             # and we get collisions. go figure.
86 0         0             @testmore = (import => [qw(!plan)]);
87              
88 0         0             Test::More->import(@testmore);
89              
90 0         0             \&Test::More::plan;
91                     } or die "-withtestmore error: $@";
92              
93             # clean up arguments to export_to_level
94 0         0         shift;
95 0         0         @EXPORT = (@test_more_exports, @Test::More::EXPORT);
96                 }
97                 else {
98             # the default - Test.pm support
99              
100 6         275         require Test;
101 6         155         Test->import(qw(ok skip));
102 6         81         @testmore = (); # reset, just in case.
103 6         70         $real_plan = \&Test::plan;
104                 }
105              
106 6 50       273     $class->export_to_level(1, undef, @_ ? @_ : @EXPORT);
107             }
108              
109             sub config {
110 42   66 42 1 1022     $Config ||= Apache::TestConfig->thaw->httpd_config;
111             }
112              
113             my $Basic_config;
114              
115             # config bits which doesn't require httpd to be found
116             sub basic_config {
117 0   0 0 1 0     $Basic_config ||= Apache::TestConfig->thaw();
118             }
119              
120             sub vars {
121 15 50   15 1 184     @_ ? @{ config()->{vars} }{ @_ } : config()->{vars};
  0         0  
122             }
123              
124             sub sok (&;$) {
125 0     0 1 0     my $sub = shift;
126 0   0     0     my $nok = shift || 1; #allow sok to have 'ok' within
127              
128 0 0 0     0     if (%SubTests and not $SubTests{ $Test::ntest }) {
129 0         0         for my $n (1..$nok) {
130 0         0             skip("skipping this subtest", 0);
131                     }
132 0         0         return;
133                 }
134              
135 0         0     my($package, $filename, $line) = caller;
136              
137             # trick ok() into reporting the caller filename/line when a
138             # sub-test fails in sok()
139 0         0     return eval <<EOE;
140             #line $line $filename
141             ok(\$sub->());
142             EOE
143             }
144              
145             #so Perl's Test.pm can be run inside mod_perl
146             sub test_pm_refresh {
147 6 50   6 1 76     if (@testmore) {
148 0         0         my $builder = Test::Builder->new;
149              
150 0         0         $builder->reset;
151              
152 0         0         $builder->output(\*STDOUT);
153 0         0         $builder->todo_output(\*STDOUT);
154              
155             # this is STDOUT because Test::More seems to put
156             # most of the stuff we want on STDERR, so it ends
157             # up in the error_log instead of where the user can
158             # see it. consider leaving it alone based on
159             # later user reports.
160 0         0         $builder->failure_output(\*STDOUT);
161                 }
162                 else {
163 6         133         $Test::TESTOUT = \*STDOUT;
164 6         59         $Test::planned = 0;
165 6         56         $Test::ntest = 1;
166 6         181         %Test::todo = ();
167                 }
168             }
169              
170             sub init_test_pm {
171 0     0 0 0     my $r = shift;
172              
173             # needed to load Apache2::RequestRec::TIEHANDLE
174 0         0     eval {require Apache2::RequestIO};
  0         0  
175 0 0       0     if (defined &Apache2::RequestRec::TIEHANDLE) {
176 0         0         untie *STDOUT;
177 0         0         tie *STDOUT, $r;
178 0         0         require Apache2::RequestRec; # $r->pool
179 0         0         require APR::Pool;
180 0     0   0         $r->pool->cleanup_register(sub { untie *STDOUT });
  0         0  
181                 }
182                 else {
183 0         0         $r->send_http_header; #1.xx
184                 }
185              
186 0         0     $r->content_type('text/plain');
187             }
188              
189             sub need_http11 {
190 0     0 1 0     require Apache::TestRequest;
191 0 0       0     if (Apache::TestRequest::install_http11()) {
192 0         0         return 1;
193                 }
194                 else {
195 0         0         push @SkipReasons,
196                        "LWP version 5.60+ required for HTTP/1.1 support";
197 0         0         return 0;
198                 }
199             }
200              
201             sub need_ssl {
202 0     0 1 0     my $vars = vars();
203 0         0     need_module([$vars->{ssl_module_name}, 'Net::SSL']);
204             }
205              
206             sub need_lwp {
207 3     3 1 193     require Apache::TestRequest;
208 3 50       145     if (Apache::TestRequest::has_lwp()) {
209 3         81         return 1;
210                 }
211                 else {
212 0         0         push @SkipReasons, "libwww-perl is not installed";
213 0         0         return 0;
214                 }
215             }
216              
217             sub plan {
218 6 50   6 1 76     init_test_pm(shift) if ref $_[0];
219 6         75     test_pm_refresh();
220              
221             # extending Test::plan's functionality, by using the optional
222             # single value in @_ coming after a ballanced %hash which
223             # Test::plan expects
224 6 100       622     if (@_ % 2) {
225 4         40         my $condition = pop @_;
226 4         42         my $ref = ref $condition;
227 4         39         my $meets_condition = 0;
228 4 100       47         if ($ref) {
229 1 50       13             if ($ref eq 'CODE') {
    0          
230             #plan tests $n, \&has_lwp
231 1         11                 $meets_condition = $condition->();
232                         }
233                         elsif ($ref eq 'ARRAY') {
234             #plan tests $n, [qw(php4 rewrite)];
235 0         0                 $meets_condition = need_module($condition);
236                         }
237                         else {
238 0         0                 die "don't know how to handle a condition of type $ref";
239                         }
240                     }
241                     else {
242             # we have the verdict already: true/false
243 3 50       33             $meets_condition = $condition ? 1 : 0;
244                     }
245              
246             # trying to emulate a dual variable (ala errno)
247 4 50       74         unless ($meets_condition) {
248 0 0       0             my $reason = join ', ',
249                           @SkipReasons ? @SkipReasons : "no reason given";
250 0         0             print "1..0 # skipped: $reason\n";
251 0         0             @SkipReasons = (); # reset
252 0         0             exit; #XXX: Apache->exit
253                     }
254                 }
255 6         209     @SkipReasons = (); # reset
256              
257 6         428     $real_plan->(@_, @testmore);
258              
259             # add to Test.pm verbose output
260 6         46760     print "# Using Apache/Test.pm version $VERSION\n";
261             }
262              
263             sub need {
264 3     3 1 30     my $need_all = 1;
265 3         30     for my $cond (@_) {
266 7 50       168         if (ref $cond eq 'HASH') {
    100          
267 0         0             while (my($reason, $value) = each %$cond) {
268 0 0       0                 $value = $value->() if ref $value eq 'CODE';
269 0 0       0                 next if $value;
270 0         0                 push @SkipReasons, $reason;
271 0         0                 $need_all = 0;
272                         }
273                     }
274                     elsif ($cond =~ /^(0|1)$/) {
275 6 50       91             $need_all = 0 if $cond == 0;
276                     }
277                     else {
278 1 50       11             $need_all = 0 unless need_module($cond);
279                     }
280                 }
281 3         152     return $need_all;
282              
283             }
284              
285             sub need_module {
286 6     6 1 91     my $cfg = config();
287              
288 1         14     my @modules = grep defined $_,
289 6 100       569         ref($_[0]) eq 'ARRAY' ? @{ $_[0] } : @_;
290              
291 6         73     my @reasons = ();
292 6         74     for (@modules) {
293 7 100       294         if (/^[a-z0-9_.]+$/) {
294 5         97             my $mod = $_;
295 5 100       144             $mod .= '.c' unless $mod =~ /\.c$/;
296 5 100       106             next if $cfg->{modules}->{$mod};
297 2 50       68             $mod = 'mod_' . $mod unless $mod =~ /^mod_/;
298 2 50       61             next if $cfg->{modules}->{$mod};
299 0 0       0             if (exists $cfg->{cmodules_disabled}->{$mod}) {
300 0         0                 push @reasons, $cfg->{cmodules_disabled}->{$mod};
301 0         0                 next;
302                         }
303                     }
304 2 50       115         die "bogus module name $_" unless /^[\w:.]+$/;
305              
306             # if the module was explicitly passed with a .c extension,
307             # do not try to eval it as a Perl module
308 2         19         my $not_found = 1;
309 2 50       43         unless (/\.c$/) {
310 2         195             eval "require $_";
311 2 50       34             $not_found = 0 unless $@;
312             #print $@ if $@;
313                     }
314 2 50       33         push @reasons, "cannot find module '$_'" if $not_found;
315              
316                 }
317 6 50       111     if (@reasons) {
318 0         0         push @SkipReasons, @reasons;
319 0         0         return 0;
320                 }
321                 else {
322 6         951         return 1;
323                 }
324             }
325              
326             sub need_min_perl_version {
327 0     0 1 0     my $version = shift;
328              
329 0 0       0     return 1 if $] >= $version;
330              
331 0         0     push @SkipReasons, "perl >= $version is required";
332 0         0     return 0;
333             }
334              
335             # currently supports only perl modules
336             sub need_min_module_version {
337 0     0 1 0     my($module, $version) = @_;
338              
339             # need_module requires the perl module
340 0 0       0     return 0 unless need_module($module);
341              
342             # support dev versions like 0.18_01
343                 return 1
344 6 0   6   133         if eval { no warnings qw(numeric); $module->VERSION($version) };
  6         58  
  6         130  
  0         0  
  0         0  
345              
346 0         0     push @SkipReasons, "$module version $version or higher is required";
347 0         0     return 0;
348             }
349              
350             sub need_cgi {
351 2     2 1 23     return _need_multi(qw(cgi cgid));
352             }
353              
354             sub need_php {
355 0     0 1 0     return _need_multi(qw(php4 php5 sapi_apache2.c));
356             }
357              
358             sub need_php4 {
359 0     0 1 0     return _need_multi(qw(php4 sapi_apache2.c));
360             }
361              
362             sub need_access {
363 0     0 0 0     return _need_multi(qw(access authz_host));
364             }
365              
366             sub need_auth {
367 0     0 0 0     return _need_multi(qw(auth auth_basic));
368             }
369              
370             sub need_imagemap {
371 0   0 0 1 0     return need_module("imagemap") || need_module("imap");
372             }
373              
374             sub _need_multi {
375              
376 2     2   23     my @check = @_;
377              
378 2         68     my $rc = 0;
379              
380                 {
381 2         21         local @SkipReasons;
  2         22  
382              
383 2         22         foreach my $module (@check) {
384 4   66     181           $rc ||= need_module($module);
385                     }
386                 }
387              
388 2         47     my $reason = join ' or ', @check;
389              
390 2 50       24     push @SkipReasons, "cannot find one of $reason"
391                     unless $rc;
392              
393 2         127     return $rc;
394             }
395              
396             sub need_apache {
397 0     0 1 0     my $version = shift;
398 0         0     my $cfg = Apache::Test::config();
399 0         0     my $rev = $cfg->{server}->{rev};
400              
401 0 0       0     if ($rev == $version) {
402 0         0         return 1;
403                 }
404                 else {
405 0         0         push @SkipReasons,
406                       "apache version $version required, this is version $rev";
407 0         0         return 0;
408                 }
409             }
410              
411             sub need_min_apache_version {
412 0     0 1 0     my $wanted = shift;
413 0         0     my $cfg = Apache::Test::config();
414 0         0     (my $current) = $cfg->{server}->{version} =~ m:^Apache/(\d\.\d+\.\d+):;
415              
416 0 0       0     if (normalize_vstring($current) < normalize_vstring($wanted)) {
417 0         0         push @SkipReasons,
418                       "apache version $wanted or higher is required," .
419                       " this is version $current";
420 0         0         return 0;
421                 }
422                 else {
423 0         0         return 1;
424                 }
425             }
426              
427             sub need_apache_version {
428 0     0 1 0     my $wanted = shift;
429 0         0     my $cfg = Apache::Test::config();
430 0         0     (my $current) = $cfg->{server}->{version} =~ m:^Apache/(\d\.\d+\.\d+):;
431              
432 0 0       0     if (normalize_vstring($current) != normalize_vstring($wanted)) {
433 0         0         push @SkipReasons,
434                       "apache version $wanted or higher is required," .
435                       " this is version $current";
436 0         0         return 0;
437                 }
438                 else {
439 0         0         return 1;
440                 }
441             }
442              
443             sub need_apache_mpm {
444 0     0 1 0     my $wanted = shift;
445 0         0     my $cfg = Apache::Test::config();
446 0         0     my $current = $cfg->{server}->{mpm};
447              
448 0 0       0     if ($current ne $wanted) {
449 0         0         push @SkipReasons,
450                       "apache $wanted mpm is required," .
451                       " this is the $current mpm";
452 0         0         return 0;
453                 }
454                 else {
455 0         0         return 1;
456                 }
457             }
458              
459             sub config_enabled {
460 0     0 0 0     my $key = shift;
461 0 0       0     defined $Config{$key} and $Config{$key} eq 'define';
462             }
463              
464             sub need_perl_iolayers {
465 0 0   0 0 0     if (my $ext = $Config{extensions}) {
466             #XXX: better test? might need to test patchlevel
467             #if support depends bugs fixed in bleedperl
468 0         0         return $ext =~ m:PerlIO/scalar:;
469                 }
470 0         0     0;
471             }
472              
473             sub need_perl {
474 0     0 1 0     my $thing = shift;
475             #XXX: $thing could be a version
476 0         0     my $config;
477              
478 0         0     my $have = \&{"need_perl_$thing"};
  0         0  
479 0 0       0     if (defined &$have) {
480 0 0       0         return 1 if $have->();
481                 }
482                 else {
483 0         0         for my $key ($thing, "use$thing") {
484 0 0       0             if (exists $Config{$key}) {
485 0         0                 $config = $key;
486 0 0       0                 return 1 if config_enabled($key);
487                         }
488                     }
489                 }
490              
491 0 0       0     push @SkipReasons, $config ?
492                   "Perl was not built with $config enabled" :
493                     "$thing is not available with this version of Perl";
494              
495 0         0     return 0;
496             }
497              
498             sub need_threads {
499 0     0 0 0     my $status = 1;
500              
501             # check APR support
502 0         0     my $build_config = Apache::TestConfig->modperl_build_config;
503              
504 0 0       0     if ($build_config) {
505 0         0         my $apr_config = $build_config->get_apr_config();
506 0 0       0         unless ($apr_config->{HAS_THREADS}) {
507 0         0             $status = 0;
508 0         0             push @SkipReasons, "Apache/APR was built without threads support";
509                     }
510                 }
511              
512             # check Perl's useithreads
513 0         0     my $key = 'useithreads';
514 0 0 0     0     unless (exists $Config{$key} and config_enabled($key)) {
515 0         0         $status = 0;
516 0         0         push @SkipReasons, "Perl was not built with 'ithreads' enabled";
517                 }
518              
519 0         0     return $status;
520             }
521              
522             sub under_construction {
523 0     0 1 0     push @SkipReasons, "This test is under construction";
524 0         0     return 0;
525             }
526              
527             sub skip_reason {
528 0   0 0 1 0     my $reason = shift || 'no reason specified';
529 0         0     push @SkipReasons, $reason;
530 0         0     return 0;
531             }
532              
533             # normalize Apache-style version strings (2.0.48, 0.9.4)
534             # for easy numeric comparison. note that 2.1 and 2.1.0
535             # are considered equivalent.
536             sub normalize_vstring {
537              
538 0     0 0 0     my @digits = shift =~ m/(\d+)\.?(\d*)\.?(\d*)/;
539              
540 0   0     0     return join '', map { sprintf("%03d", $_ || 0) } @digits;
  0         0  
541             }
542              
543             # have_ functions are the same as need_ but they don't populate
544             # @SkipReasons
545             for my $func (@have) {
546 6     6   131     no strict 'refs';
  6         59  
  6         107  
547                 (my $real_func = $func) =~ s/^have_/need_/;
548                 *$func = sub {
549             # be nice to poor souls calling functions with $_ argument in
550             # the foreach loop, etc.!
551 1     1   9         local $_;
552 1         11         local @SkipReasons;
553 1         15         return $real_func->(@_);
554                 };
555             }
556              
557             package Apache::TestToString;
558              
559             sub TIEHANDLE {
560 0     0         my $string = "";
561 0               bless \$string;
562             }
563              
564             sub PRINT {
565 0     0         my $string = shift;
566 0               $$string .= join '', @_;
567             }
568              
569             sub start {
570 0     0         tie *STDOUT, __PACKAGE__;
571 0               Apache::Test::test_pm_refresh();
572             }
573              
574             sub finish {
575 0     0         my $s;
576                 {
577 0                   my $o = tied *STDOUT;
  0            
578 0                   $s = $$o;
579                 }
580 0               untie *STDOUT;
581 0               $s;
582             }
583              
584             1;
585             __END__
586            
587            
588             =head1 NAME
589            
590             Apache::Test - Test.pm wrapper with helpers for testing Apache
591            
592             =head1 SYNOPSIS
593            
594             use Apache::Test;
595            
596             =head1 DESCRIPTION
597            
598             B<Apache::Test> is a wrapper around the standard C<Test.pm> with
599             helpers for testing an Apache server.
600            
601             =head1 FUNCTIONS
602            
603             =over 4
604            
605             =item plan
606            
607             This function is a wrapper around C<Test::plan>:
608            
609             plan tests => 3;
610            
611             just like using Test.pm, plan 3 tests.
612            
613             If the first argument is an object, such as an C<Apache::RequestRec>
614             object, C<STDOUT> will be tied to it. The C<Test.pm> global state will
615             also be refreshed by calling C<Apache::Test::test_pm_refresh>. For
616             example:
617            
618             plan $r, tests => 7;
619            
620             ties STDOUT to the request object C<$r>.
621            
622             If there is a last argument that doesn't belong to C<Test::plan>
623             (which expects a balanced hash), it's used to decide whether to
624             continue with the test or to skip it all-together. This last argument
625             can be:
626            
627             =over
628            
629             =item * a C<SCALAR>
630            
631             the test is skipped if the scalar has a false value. For example:
632            
633             plan tests => 5, 0;
634            
635             But this won't hint the reason for skipping therefore it's better to
636             use need():
637            
638             plan tests => 5,
639             need 'LWP',
640             { "not Win32" => sub { $^O eq 'MSWin32'} };
641            
642             see C<need()> for more info.
643            
644             =item * an C<ARRAY> reference
645            
646             need_module() is called for each value in this array. The test is
647             skipped if need_module() returns false (which happens when at least
648             one C or Perl module from the list cannot be found).
649            
650             Watch out for case insensitive file systems or duplicate modules
651             with the same name. I.E. If you mean mod_env.c
652             need_module('mod_env.c')
653             Not
654             need_module('env')
655            
656             =item * a C<CODE> reference
657            
658             the tests will be skipped if the function returns a false value. For
659             example:
660            
661             plan tests => 5, need_lwp;
662            
663             the test will be skipped if LWP is not available
664            
665             =back
666            
667             All other arguments are passed through to I<Test::plan> as is.
668            
669             =item ok
670            
671             Same as I<Test::ok>, see I<Test.pm> documentation.
672            
673             =item sok
674            
675             Allows to skip a sub-test, controlled from the command line. The
676             argument to sok() is a CODE reference or a BLOCK whose return value
677             will be passed to ok(). By default behaves like ok(). If all sub-tests
678             of the same test are written using sok(), and a test is executed as:
679            
680             % ./t/TEST -v skip_subtest 1 3
681            
682             only sub-tests 1 and 3 will be run, the rest will be skipped.
683            
684             =item skip
685            
686             Same as I<Test::skip>, see I<Test.pm> documentation.
687            
688             =item test_pm_refresh
689            
690             Normally called by I<Apache::Test::plan>, this function will refresh
691             the global state maintained by I<Test.pm>, allowing C<plan> and
692             friends to be called more than once per-process. This function is not
693             exported.
694            
695             =back
696            
697             Functions that can be used as a last argument to the extended plan().
698             Note that for each C<need_*> function there is a C<have_*> equivalent
699             that performs the exact same function except that it is designed to
700             be used outside of C<plan()>. C<need_*> functions have the side effect
701             of generating skip messages, if the test is skipped. C<have_*> functions
702             don't have this side effect. In other words, use C<need_apache()>
703             with C<plan()> to decide whether a test will run, but C<have_apache()>
704             within test logic to adjust expectations based on older or newer
705             server versions.
706            
707             =over
708            
709             =item need_http11
710            
711             plan tests => 5, need_http11;
712            
713             Require HTTP/1.1 support.
714            
715             =item need_ssl
716            
717             plan tests => 5, need_ssl;
718            
719             Require SSL support.
720            
721             Not exported by default.
722            
723             =item need_lwp
724            
725             plan tests => 5, need_lwp;
726            
727             Require LWP support.
728            
729             =item need_cgi
730            
731             plan tests => 5, need_cgi;
732            
733             Requires mod_cgi or mod_cgid to be installed.
734            
735             =item need_php
736            
737             plan tests => 5, need_php;
738            
739             Requires a PHP module to be installed (version 4 or 5).
740            
741             =item need_php4
742            
743             plan tests => 5, need_php4;
744            
745             Requires a PHP version 4 module to be installed.
746            
747             =item need_imagemap
748            
749             plan tests => 5, need_imagemap;
750            
751             Requires a mod_imagemap or mod_imap be installed
752            
753             =item need_apache
754            
755             plan tests => 5, need_apache 2;
756            
757             Requires Apache 2nd generation httpd-2.x.xx
758            
759             plan tests => 5, need_apache 1;
760            
761             Requires Apache 1st generation (apache-1.3.xx)
762            
763             See also C<need_min_apache_version()>.
764            
765             =item need_min_apache_version
766            
767             Used to require a minimum version of Apache.
768            
769             For example:
770            
771             plan tests => 5, need_min_apache_version("2.0.40");
772            
773             requires Apache 2.0.40 or higher.
774            
775             =item need_apache_version
776            
777             Used to require a specific version of Apache.
778            
779             For example:
780            
781             plan tests => 5, need_apache_version("2.0.40");
782            
783             requires Apache 2.0.40.
784            
785             =item need_apache_mpm
786            
787             Used to require a specific Apache Multi-Processing Module.
788            
789             For example:
790            
791             plan tests => 5, need_apache_mpm('prefork');
792            
793             requires the prefork MPM.
794            
795             =item need_perl
796            
797             plan tests => 5, need_perl 'iolayers';
798             plan tests => 5, need_perl 'ithreads';
799            
800             Requires a perl extension to be present, or perl compiled with certain
801             capabilities.
802            
803             The first example tests whether C<PerlIO> is available, the second
804             whether:
805            
806             $Config{useithread} eq 'define';
807            
808             =item need_min_perl_version
809            
810             Used to require a minimum version of Perl.
811            
812             For example:
813            
814             plan tests => 5, need_min_perl_version("5.008001");
815            
816             requires Perl 5.8.1 or higher.
817            
818             =item need_module
819            
820             plan tests => 5, need_module 'CGI';
821             plan tests => 5, need_module qw(CGI Find::File);
822             plan tests => 5, need_module ['CGI', 'Find::File', 'cgid'];
823            
824             Requires Apache C and Perl modules. The function accept a list of
825             arguments or a reference to a list.
826            
827             In case of C modules, depending on how the module name was passed it
828             may pass through the following completions:
829            
830             =over
831            
832             =item 1 need_module 'proxy_http.c'
833            
834             If there is the I<.c> extension, the module name will be looked up as
835             is, i.e. I<'proxy_http.c'>.
836            
837             =item 2 need_module 'mod_cgi'
838            
839             The I<.c> extension will be appended before the lookup, turning it into
840             I<'mod_cgi.c'>.
841            
842             =item 3 need_module 'cgi'
843            
844             The I<.c> extension and I<mod_> prefix will be added before the
845             lookup, turning it into I<'mod_cgi.c'>.
846            
847             =back
848            
849             =item need_min_module_version
850            
851             Used to require a minimum version of a module
852            
853             For example:
854            
855             plan tests => 5, need_min_module_version(CGI => 2.81);
856            
857             requires C<CGI.pm> version 2.81 or higher.
858            
859             Currently works only for perl modules.
860            
861             =item need
862            
863             plan tests => 5,
864             need 'LWP',
865             { "perl >= 5.8.0 and w/ithreads is required" =>
866             ($Config{useperlio} && $] >= 5.008) },
867             { "not Win32" => sub { $^O eq 'MSWin32' },
868             "foo is disabled" => \&is_foo_enabled,
869             },
870             'cgid';
871            
872             need() is more generic function which can impose multiple requirements
873             at once. All requirements must be satisfied.
874            
875             need()'s argument is a list of things to test. The list can include
876             scalars, which are passed to need_module(), and hash references. If
877             hash references are used, the keys, are strings, containing a reason
878             for a failure to satisfy this particular entry, the values are the
879             condition, which are satisfaction if they return true. If the value is
880             0 or 1, it used to decide whether the requirements very satisfied, so
881             you can mix special C<need_*()> functions that return 0 or 1. For
882             example:
883            
884             plan tests => 1, need 'Compress::Zlib', 'deflate',
885             need_min_apache_version("2.0.49");
886            
887             If the scalar value is a string, different from 0 or 1, it's passed to
888             I<need_module()>. If the value is a code reference, it gets executed
889             at the time of check and its return value is used to check the
890             condition. If the condition check fails, the provided (in a key)
891             reason is used to tell user why the test was skipped.
892            
893             In the presented example, we require the presence of the C<LWP> Perl
894             module, C<mod_cgid>, that we run under perl E<gt>= 5.7.3 on Win32.
895            
896             It's possible to put more than one requirement into a single hash
897             reference, but be careful that the keys will be different.
898            
899             It's also important to mention to avoid using:
900            
901             plan tests => 1, requirement1 && requirement2;
902            
903             technique. While test-wise that technique is equivalent to:
904            
905             plan tests => 1, need requirement1, requirement2;
906            
907             since the test will be skipped, unless all the rules are satisfied,
908             it's not equivalent for the end users. The second technique, deploying
909             C<need()> and a list of requirements, always runs all the requirement
910             checks and reports all the missing requirements. In the case of the
911             first technique, if the first requirement fails, the second is not
912             run, and the missing requirement is not reported. So let's say all the
913             requirements are missing Apache modules, and a user wants to satisfy
914             all of these and run the test suite again. If all the unsatisfied
915             requirements are reported at once, she will need to rebuild Apache
916             once. If only one requirement is reported at a time, she will have to
917             rebuild Apache as many times as there are elements in the C<&&>
918             statement.
919            
920             Also see plan().
921            
922             =item under_construction
923            
924             plan tests => 5, under_construction;
925            
926             skip all tests, noting that the tests are under construction
927            
928             =item skip_reason
929            
930             plan tests => 5, skip_reason('my custom reason');
931            
932             skip all tests. the reason you specify will be given at runtime.
933             if no reason is given a default reason will be used.
934            
935             =back
936            
937             =head1 Additional Configuration Variables
938            
939             =item basic_config
940            
941             my $basic_cfg = Apache::Test::basic_config();
942             $basic_cfg->write_perlscript($file, $content);
943            
944             C<basic_config()> is similar to C<config()>, but doesn't contain any
945             httpd-specific information and should be used for operations that
946             don't require any httpd-specific knowledge.
947            
948             =item config
949            
950             my $cfg = Apache::Test::config();
951             my $server_rev = $cfg->{server}->{rev};
952             ...
953            
954             C<config()> gives an access to the configuration object.
955            
956             =item vars
957            
958             my $serverroot = Apache::Test::vars->{serverroot};
959             my $serverroot = Apache::Test::vars('serverroot');
960             my($top_dir, $t_dir) = Apache::Test::vars(qw(top_dir t_dir));
961            
962             C<vars()> gives an access to the configuration variables, otherwise
963             accessible as:
964            
965             $vars = Apache::Test::config()->{vars};
966            
967             If no arguments are passed, the reference to the variables hash is
968             returned. If one or more arguments are passed the corresponding values
969             are returned.
970            
971             =head1 Test::More Integration
972            
973             There are a few caveats if you want to use I<Apache::Test> with
974             I<Test::More> instead of the default I<Test> backend. The first is
975             that I<Test::More> requires you to use its own C<plan()> function
976             and not the one that ships with I<Apache::Test>. I<Test::More> also
977             defines C<ok()> and C<skip()> functions that are different, and
978             simply C<use>ing both modules in your test script will lead to redefined
979             warnings for these subroutines.
980            
981             To assist I<Test::More> users we have created a special I<Apache::Test>
982             import tag, C<:withtestmore>, which will export all of the standard
983             I<Apache::Test> symbols into your namespace except the ones that collide
984             with I<Test::More>.
985            
986             use Apache::Test qw(:withtestmore);
987             use Test::More;
988            
989             plan tests => 1; # Test::More::plan()
990            
991             ok ('yes', 'testing ok'); # Test::More::ok()
992            
993             Now, while this works fine for standard client-side tests
994             (such as C<t/basic.t>), the more advanced features of I<Apache::Test>
995             require using I<Test::More> as the sole driver behind the scenes.
996            
997             Should you choose to use I<Test::More> as the backend for
998             server-based tests (such as C<t/response/TestMe/basic.pm>) you will
999             need to use the C<-withtestmore> action tag:
1000            
1001             use Apache::Test qw(-withtestmore);
1002            
1003             sub handler {
1004            
1005             my $r = shift;
1006            
1007             plan $r, tests => 1; # Test::More::plan() with
1008             # Apache::Test features
1009            
1010             ok ('yes', 'testing ok'); # Test::More::ok()
1011             }
1012            
1013             C<-withtestmore> tells I<Apache::Test> to use I<Test::More>
1014             instead of I<Test.pm> behind the scenes. Note that you are not
1015             required to C<use Test::More> yourself with the C<-withtestmore>
1016             option and that the C<use Test::More tests =E<gt> 1> syntax
1017             may have unexpected results.
1018            
1019             Note that I<Test::More> version 0.49, available within the
1020             I<Test::Simple> 0.49 distribution on CPAN, or greater is required
1021             to use this feature.
1022            
1023             Because I<Apache:Test> was initially developed using I<Test> as
1024             the framework driver, complete I<Test::More> integration is
1025             considered experimental at this time - it is supported as best as
1026             possible but is not guaranteed to be as stable as the default I<Test>
1027             interface at this time.
1028            
1029             =head1 Apache::TestToString Class
1030            
1031             The I<Apache::TestToString> class is used to capture I<Test.pm> output
1032             into a string. Example:
1033            
1034             Apache::TestToString->start;
1035            
1036             plan tests => 4;
1037            
1038             ok $data eq 'foo';
1039            
1040             ...
1041            
1042             # $tests will contain the Test.pm output: 1..4\nok 1\n...
1043             my $tests = Apache::TestToString->finish;
1044            
1045             =head1 SEE ALSO
1046            
1047             The Apache-Test tutorial:
1048             L<http://perl.apache.org/docs/general/testing/testing.html>.
1049            
1050             L<Apache::TestRequest|Apache::TestRequest> subclasses LWP::UserAgent and
1051             exports a number of useful functions for sending request to the Apache test
1052             server. You can then test the results of those requests.
1053            
1054             Use L<Apache::TestMM|Apache::TestMM> in your F<Makefile.PL> to set up your
1055             distribution for testing.
1056            
1057             =head1 AUTHOR
1058            
1059             Doug MacEachern with contributions from Geoffrey Young, Philippe
1060             M. Chiasson, Stas Bekman and others.
1061            
1062             Questions can be asked at the test-dev <at> httpd.apache.org list
1063             For more information see: http://httpd.apache.org/test/.
1064            
1065             =cut
1066