NAME

    Test::Out - Test output from FILEHANDLE

SYNOPSIS

    use Test::Out;
    my $out = Test::Out->new( output => *STDOUT, tests => 4 );

    # Or ...

    my $out = Test::Out->new(tests => 4);
    $out->redirect( output => *STDOUT );

    ## This will go to a place that your harness can see
    $out->diag("Testing is* functions");

    ## But this will not be displayed but captured for test methods
    $some->method_that_prints("This is a test\n");
    $out->is_output("This is a test\n", "test 1");
    $out->isnt_output("Han shot first", "test 2");

    $out->diag("Testing regex functions");
    CORE::print "A random number: @{[int rand 100]}\n";
    $out->like_output(qr/random number: \d+/, "test 3");
    $out->unlike_output(qr/i like pickles$/, "test 4");

    $out->restore;

    ## This will be printed to STDOUT
    print "Done.\n";

DESCRIPTION

Test out is another Test::Builder application that implements a few of the well known test facilities except the result of output to an IO::Handle is used. This could be used to capture output being printed to a file, but it's ideal for output being sent to STDOUT or STDERR.

See the SYNOPSIS for an example use.

AUTHOR

Lane Davis <cpan@upt.org>

FUNCTIONS

METHODS

$out->new(%options)

The Test::Out package constructor has several arguments, some required some optional

REQUIRED OPTIONS

The following options must be present in the hash passed to the constructor:

THE NUMBER OF PLANNED TESTS

tests => $Tests

The number of tests are simply passed to Test::Builder

NON-REQUIRED OPTIONS

THE OUTPUT YOU WISH TO TEST

Actually the output key is required, but you have the option of passing the key into the constructor or to the redirect method. This is useful if you have several segments of tests wrapped with redirect and restore.

output => *FH

The output argument is required and may contain either a FILEHANDLE typeglob, or

output => \*FHREF

The output key may also point to a typeglob reference

$out->redirect

$out->redirect(output => *FH)

$out->redirect(output => \*FH)

This method will be automatically invoked by the constructor if the output key is passed to new.

TESTS

$out->is_output(EXPR, NAME)

$out->was_output(EXPR, NAME)

Tests the last output buffer against EXPR. If there isn't a perfect string comparison the test fails. Pay particular attention to possible newlines in the last output. If you're unsure either paste the contents of $\ to your comparitor or use the like method.

The was_output method is an alias for is_output.

$out->isnt_output(EXPR, NAME)

$out->wasnt_output(EXPR, NAME)

This is the inverse of is_output, the negation of the comparing EXPR to the last printed output is performed.

The wasnt_output method is an alias for isnt_output.

$out->like_output(qr/STRING/, NAME)

This performs a test with the last output and a compiled regular expression as its first argument.

$out->unlike_output(qr/STRING/, NAME)

This performs a negated test with the last output and a compiled regular expression as its first argument.

$out->cmp_output(OP, EXPR, NAME)

This performs a comparison allowing you to pass your own perl binary operator as the first arugment (e.g., "==", "eq", etc).

$out->diag(@messages)

Prints a diagnostic message