NAME

Test::Group::Tester - Test Test::Group extensions

VERSION

Test::Group::Tester version 0.01

SYNOPSIS

  use Test::More tests => 1;
  use Test::Group::Tester;
  testscript_ok('#line '.(__LINE__+1)."\n".<<'EOSCRIPT', 3);
    use Test::More;
    use Test::Group;
    # Test a passing test group
    want_test('pass', "this_should_pass");
    test this_should_pass => sub {
        ok 1, "1 is true";
        ok 2, "2 is true";
    };
    # Test a failing test group
    want_test('fail', "this_should_fail",
        fail_diag("0 is true", 0, __LINE__+5),
        fail_diag("this_should_fail", 1, __LINE__+5),
    );
    test this_should_fail => sub {
        ok 1, "1 is true";
        ok 0, "0 is true";
    };
    # Test a skipped test group
    want_test('skip', "just because I can");
    skip_next_test("just because I can");
    test this_should_be_skipped => sub {
        ok 0;
    };
  EOSCRIPT

DESCRIPTION

Test the behavior of a Test::Harness compatible test script, by spawning an external process to run the script and capturing its STDOUT and STDERR. Includes support for matching the failed test diagnostic messages produced by Test::Group and Test::Builder.

Useful when writing tests for Test::Group extension modules, see Test::Group::Extending.

This module is used within the test suite of Test::Group itself, so several usage examples can be found by searching for "testscript_ok" in the files in Test::Group's t subdirectory.

FUNCTIONS EXPORTED BY DEFAULT

testscript_ok($source, $plan, $name)

A test predicate for checking that a test script acts as expected. Runs the script capturing STDOUT and STDERR and fails if anything unexpected happens.

The expected behavior of the script is defined by calling want_test() from within the script, just before running each test.

$source is the body of the test script, as a single multi-line string.

$plan is the number of tests that the test script will run.

$name is a name for this test.

Some code will be prepended to $source, to make the want_test() and fail_diag() functions available and to set the test plan to $plan.

Tip: include a "#line" directive in your script source as shown in the SYNOPSIS above, so that the reported line numbers for problems will point to the correct line in your source file.

TEST SCRIPT FUNCTIONS

The following functions are for use from within the script under test. They are not exported by default.

want_test($type, $name, @diag)

Declares that the next test will pass or fail or be skipped according to $type, will have name $name and will produce the diagnostic output lines listed in @diag.

$type must be one of the strings 'pass', 'fail', 'skip'. $name can be undef for a test without a name. The elements of @diag can be strings for an exact match, or regular expressions prefixed with "/" or compiled with "qr//".

Note that diagnostic lines consist of a hash character followed by a space and then the diagnostic message. The strings and patterns passed to want_test() must include this prefix.

fail_diag($test_name [,$from_test_builder] [,$line] [,$file])

Call only in a list context, and pass the results to want_test() as diagnostic line patterns.

Returns the diagnostic line pattern(s) to match output from a failed test. $test_name is the name of the test, or undef for a nameless test. $line should be defined only if a file and line diagnostic is expected, and should give the expected line number. $file is the filename for the failed test diagnostic, it defaults to the current file.

$from_test_builder should be true if Test::Builder will produce the diagnostic, false if the diagnostic will come from Test::Group. The expected text will be adjusted according to the version of Test::Builder or Test::Group in use.

AUTHORS

Nick Cleaton <ncleaton@cpan.org>

Dominique Quatravaux <domq@cpan.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.