Apache::Test

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:

* a SCALAR

the test is skipped if the scalar has a false value. For example:

  plan tests => 5, 0;

But this won't hint the reason for skipping therefore it's better to use need():

  plan tests => 5,
      need 'LWP', 
           { "not Win32" => sub { $^O eq 'MSWin32'} };

see "need()" for more info.

* an ARRAY reference

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

* a CODE reference

the tests will be skipped if the function returns a false value. For example:

    plan tests => 5, \&need_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 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(). Note that for each "need_*" function there is a "have_*" equivalent that performs the exact same function except that it is designed to be used outside of "plan()". "need_*" functions have the side effect of generating skip messages, if the test is skipped. "have_*" functions don't have this side effect. In other words, use "need_apache()" with "plan()" to decide whether a test will run, but "have_apache()" within test logic to adjust expectations based on older or newer server versions.

need_http11

  plan tests => 5, &need_http11;

Require HTTP/1.1 support.

need_ssl

  plan tests => 5, &need_ssl;

Require SSL support.

Not exported by default.

need_lwp

  plan tests => 5, &need_lwp;

Require LWP support.

need_cgi

  plan tests => 5, &need_cgi;

Requires mod_cgi or mod_cgid to be installed.

need_php

  plan tests => 5, need_php;

Requires mod_php4 or mod_php5 to be installed.

need_apache

  plan tests => 5, need_apache 2;

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

  plan tests => 5, need_apache 1;

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

See also "need_min_apache_version()".

need_min_apache_version

Used to require a minimum version of Apache.

For example:

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

requires Apache 2.0.40 or higher.

need_apache_version

Used to require a specific version of Apache.

For example:

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

requires Apache 2.0.40.

need_apache_mpm

Used to require a specific Apache Multi-Processing Module.

For example:

  plan tests => 5, need_apache_mpm('prefork');

requires the prefork MPM.

need_perl

  plan tests => 5, need_perl 'iolayers';
  plan tests => 5, need_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';

need_min_perl_version

Used to require a minimum version of Perl.

For example:

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

requires Perl 5.8.1 or higher.

need_module

  plan tests => 5, need_module 'CGI';
  plan tests => 5, need_module qw(CGI Find::File);
  plan tests => 5, need_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:

need_min_module_version

Used to require a minimum version of a module

For example:

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

requires "CGI.pm" version 2.81 or higher.

Currently works only for perl modules.

1 need_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 need_module 'mod_cgi': The .c extension will be appended before the lookup, turning it into 'mod_cgi.c'.
3 need_module 'cgi': The .c extension and mod_ prefix will be added before the lookup, turning it into 'mod_cgi.c'.

need

  plan tests => 5,
      need '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';

need() is more generic function which can impose multiple requirements at once. All requirements must be satisfied.

need()'s argument is a list of things to test. The list can include scalars, which are passed to need_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 0 or 1, it used to decide whether the requirements very satisfied, so you can mix special "need_*()" functions that return 0 or 1. For example:

  plan tests => 1, need 'Compress::Zlib', 'deflate',
      need_min_apache_version("2.0.49");

If the scalar value is a string, different from 0 or 1, it's passed to need_module(). 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().

under_construction

  plan tests => 5, under_construction;

skip all tests, noting that the tests are under construction

skip_reason

  plan tests => 5, skip_reason('my custom reason');

skip all tests. the reason you specify will be given at runtime. if no reason is given a default reason will be used.

Additional Configuration Variables

basic_config

  my $basic_cfg = Apache::Test::basic_config();
  $basic_cfg->write_perlscript($file, $content);

"basic_config()" is similar to "config()", but doesn't contain any httpd-specific information and should be used for operations that don't require any httpd-specific knowledge.

config

  my $cfg = Apache::Test::config();
  my $server_rev = $cfg->{server}->{rev};
  ...

"config()" gives an access to the configuration object.

vars

  my $serverroot = Apache::Test::vars->{serverroot};
  my $serverroot = Apache::Test::vars('serverroot');
  my($top_dir, $t_dir) = Apache::Test::vars(qw(top_dir t_dir));

"vars()" gives an access to the configuration variables, otherwise accessible as:

  $vars = Apache::Test::config()->{vars};

If no arguments are passed, the reference to the variables hash is returned. If one or more arguments are passed the corresponding values are returned.

Test::More Integration

There are a few caveats if you want to use Apache::Test with Test::More instead of the default Test backend. The first is that Test::More requires you to use its own "plan()" function and not the one that ships with Apache::Test. Test::More also defines "ok()" and "skip()" functions that are different, and simply "use"ing both modules in your test script will lead to redefined warnings for these subroutines.

To assist Test::More users we have created a special Apache::Test import tag, ":withtestmore", which will export all of the standard Apache::Test symbols into your namespace except the ones that collide with Test::More.

    use Apache::Test qw(:withtestmore);
    use Test::More;

    plan tests => 1;           # Test::More::plan()

    ok ('yes', 'testing ok');  # Test::More::ok()

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

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

Additional Configuration Variables

Test::More Integration

Apache::TestToString Class

SEE ALSO

AUTHOR

Index