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 skip_unless()

  skip_unless({sub { $a == $b } => "$a != $b"}, 'LWP');
  plan tests => 5;

  see skip_unless() 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.

skip_unless

skip_unless({sub {$a==$b} => "$a != $b!"
             sub {$a==1}  => "$a != 1!"},
            'LWP',
            'cgi_d',
             {sub {0} => "forced to be skipped"},
           );

skip_unless() can be called before plan(), to decide whether to skip the whole test or not. plan() won't be reached if skip_unless decides to skip the test.

skip_unless()'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 key and a reason for failure as a value. The condition code is run and if it fails the provided reason is used to tell user why the test was skipped.

Also see plan().

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.

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;