Apache::Test(3)       User Contributed Perl Documentation      Apache::Test(3)

       Apache::Test - wrapper with helpers for testing Apache

           use Apache::Test;

       Apache::Test is a wrapper around the standard "" with helpers
       for testing an Apache server.

           This function is a wrapper around "Test::plan":

               plan tests => 3;

           just like using, plan 3 tests.

           If the first argument is an object, such as an "Apache::RequestRec"
           object, "STDOUT" will be tied to it. The "" global state
           will also be refreshed by calling "Apache::Test::test_pm_refresh".
           For example:

               plan $r, tests => 7;

           ties STDOUT to the request object $r.

           If there is a last argument that doesn't belong to "Test::plan"
           (which expects a balanced hash), it's used to decide whether to
           continue with the test or to skip it all-together. This last argu-
           ment can be:

           o a "SCALAR"
               the test is skipped if the scalar has a false value. For exam-

                 plan tests => 5, 0;

               But this won't hint the reason for skipping therefore it's bet-
               ter to use have():

                 plan tests => 5,
                     have 'LWP',
                          { "perl >= 5.7.3 is required" => sub { $] >= 5.007003 } };

               see have() for more info.

           o an "ARRAY" reference
               have_module() is called for each value in this array. The test
               is skipped if have_module() returns false (which happens when
               at least one C or Perl module from the list cannot be found).

           o a "CODE" reference
               the tests will be skipped if the function returns a false
               value. For example:

                   plan tests => 5, \&have_lwp;

               the test will be skipped if LWP is not available

           All other arguments are passed through to Test::plan as is.

       ok  Same as Test::ok, see documentation.

       sok Allows to skip a sub-test, controlled from the command line.  The
           argument to sok() is a CODE reference or a BLOCK whose return value
           will be passed to ok(). By default behaves like ok(). If all sub-
           tests of the same test are written using sok(), and a test is exe-
           cuted as:

             % ./t/TEST -v skip_subtest 1 3

           only sub-tests 1 and 3 will be run, the rest will be skipped.

           Same as Test::skip, see documentation.

           Normally called by Apache::Test::plan, this function will refresh
           the global state maintained by, allowing "plan" and friends
           to be called more than once per-process.  This function is not

       Functions that can be used as a last argument to the extended plan():

         plan tests => 5, &have_http11;

           Require HTTP/1.1 support.

             plan tests => 5, &have_ssl;

           Require SSL support.

           Not exported by default.

             plan tests => 5, &have_lwp;

           Require LWP support.

             plan tests => 5, &have_cgi;

           Requires mod_cgi or mod_cgid to be installed.

             plan tests => 5, have_apache 2;

           Requires httpd-2.x (apache-2.x).

             plan tests => 5, have_apache 1;

           Requires apache-1.3.x.

             plan tests => 5, have_perl 'iolayers';
             plan tests => 5, have_perl 'ithreads';

           Requires a perl extension to be present, or perl compiled with cer-
           tain capabilities.

           The first example tests whether "PerlIO" is available, the second

             $Config{useithread} eq 'define';

             plan tests => 5, have_module 'CGI';
             plan tests => 5, have_module qw(CGI Find::File);
             plan tests => 5, have_module ['CGI', 'Find::File', 'cgid'];

           Requires Apache C and Perl modules. The function accept a list of
           arguments or a reference to a list.

           In case of C modules, depending on how the module name was passed
           it may pass through the following completions:

           1 have_module 'proxy_http.c'
               If there is the .c extension, the module name will be looked up
               as is, i.e. 'proxy_http.c'.

           2 have_module 'mod_cgi'
               The .c extension will be appended before the lookup, turning it
               into 'mod_cgi.c'.

           3 have_module 'cgi'
               The .c extension and mod_ prefix will be added before the
               lookup, turning it into 'mod_cgi.c'.

             plan tests => 5,
                 have 'LWP',
                      { "perl >= 5.7.3 is required" => sub { $] >= 5.007003   } },
                      { "not Win32"                 => sub { $^O eq 'MSWin32' } },

           have() is more generic function which can impose multiple require-
           ments at once. All requirements must be satisfied.

           have()'s argument is a list of things to test. The list can include
           scalars, which are passed to have_module(), and hash references.
           The hash references have a condition code reference as a value and
           a reason for failure as a key. The condition code is run and if it
           fails the provided reason is used to tell user why the test was

           In the presented example, we require the presense of the "LWP" Perl
           module, "mod_cgid", that we run under perl >= 5.7.3 on Win32.

           It's possible to put more than one requirement into a single hash
           reference, but be careful that the keys will be different:

                 have 'LWP',
                      { "perl >= 5.7.3 is required" => sub { $] >= 5.007003   },
                        "not Win32"                 => sub { $^O eq 'MSWin32' },

           Also see plan().

Apache::TestToString Class
       The Apache::TestToString class is used to capture output into a
       string.  Example:


           plan tests => 4;

           ok $data eq 'foo';


           # $tests will contain the output: 1..4\nok 1\n...
           my $tests = Apache::TestToString->finish;

perl v5.8.0                       2002-09-10                   Apache::Test(3)