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 have():

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

  see have() for more info.

• 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).

• 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 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():

have_http11

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_apache_mpm

Used to require a specific Apache Multi-Processing Module.

For example:

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

requires the prefork MPM.

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'

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'.

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 0 or 1, it used to decide whether the requirements very satisfied, so you can mix special have_*() functions that return 0 or 1. For example:

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

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

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 useing 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;

SEE ALSO

The Apache-Test tutorial: http://perl.apache.org/docs/general/testing/testing.html.

Apache::TestRequest subclasses LWP::UserAgent and exports a number of useful functions for sending request to the Apache test server. You can then test the results of those requests.

Use Apache::TestMM in your Makefile.PL to set up your distribution for testing.

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/.