Apache::Test - Test.pm wrapper with helpers for testing Apache


NAME

Apache::Test - Test.pm wrapper with helpers for testing Apache


SYNOPSIS

    use Apache::Test;


DESCRIPTION

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


FUNCTIONS

plan
This function is a wrapper around Test::plan:
    plan tests => 3;

just like using Test.pm, plan 3 tests.

If the first argument is an object, such as an Apache::RequestRec object, STDOUT will be tied to it. The Test.pm 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 argument can be:

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

ok
Same as Test::ok, see Test.pm 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 executed as:
  % ./t/TEST -v skip_subtest 1 3

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

skip
Same as Test::skip, see Test.pm documentation.

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

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

  plan tests => 5, &have_http11;

Require HTTP/1.1 support.

have_ssl
  plan tests => 5, &have_ssl;

Require SSL support.

Not exported by default.

have_lwp
  plan tests => 5, &have_lwp;

Require LWP support.

have_cgi
  plan tests => 5, &have_cgi;

Requires mod_cgi or mod_cgid to be installed.

have_apache
  plan tests => 5, have_apache 2;

Requires Apache 2nd generation httpd-2.x.xx

  plan tests => 5, have_apache 1;

Requires Apache 1st generation (apache-1.3.xx)

See also have_min_apache_version().

have_min_apache_version
Used to require a minimum version of Apache.

For example:

  plan tests => 5, have_min_apache_version("2.0.40");

requires Apache 2.0.40 or higher.

have_apache_version
Used to require a specific version of Apache.

For example:

  plan tests => 5, have_apache_version("2.0.40");

requires Apache 2.0.40.

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

Requires a perl extension to be present, or perl compiled with certain capabilities.

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

  $Config{useithread} eq 'define';
have_min_perl_version
Used to require a minimum version of Perl.

For example:

  plan tests => 5, have_min_perl_version("5.008001");

requires Perl 5.8.1 or higher.

have_module
  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:

have_min_module_version
Used to require a minimum version of a module

For example:

  plan tests => 5, have_min_module_version(CGI => 2.81);

requires CGI.pm version 2.81 or higher.

Currently works only for perl modules.

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

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

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

have
  plan tests => 5,
      have 'LWP',
           { "perl >= 5.8.0 and w/ithreads is required" => 
             ($Config{useperlio} && $] >= 5.008) },
           { "not Win32"                 => sub { $^O eq 'MSWin32' },
             "foo is disabled"           => \&is_foo_enabled,
           },
           'cgid';

have() is more generic function which can impose multiple requirements 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. If hash references are used, the keys, are strings, containing a reason for a failure to satisfy this particular entry, the valuees are the condition, which are satisfaction if they return true. If the value is a scalar it's used as is. If the value is a code reference, it gets executed at the time of check and its return value is used to check the condition. If the condition check fails, the provided (in a key) reason is used to tell user why the test was skipped.

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.

Also see plan().


Apache::TestToString Class

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

    Apache::TestToString->start;
    plan tests => 4;
    ok $data eq 'foo';
    ...
    # $tests will contain the Test.pm output: 1..4\nok 1\n...
    my $tests = Apache::TestToString->finish;


AUTHOR

Doug MacEachern with contributions from Geoffrey Young, Philippe M. Chiasson, Stas Bekman and others.

Questions can be asked at the test-dev <at> httpd.apache.org list For more information see: http://httpd.apache.org/test/.

 Apache::Test - Test.pm wrapper with helpers for testing Apache