/ 
Test-Output-0.05
River stage four • 216 direct dependents • 1505 total dependents
/ Test::Output

NAME

Test::Output - Utilities to test STDOUT and STDERR messages.

VERSION

Version 0.05

SYNOPSIS

use Test::More tests => 4;
use Test::Output;

sub writer {
  print "Write out.\n";
  print STDERR "Error out.\n";
}

stdout_is(\&writer,"Write out.\n",'Test STDOUT');

stderr_isnt(\&writer,"No error out.\n",'Test STDERR');

output_is(
          \&writer,
          "Write out.\n",
          "Error out.\n",
          'Test STDOUT & STDERR'
        );

DESCRIPTION

Test::Output provides a simple interface for testing output send to STDOUT or STDERR. A number of different utilies are included to try and be as flexible as possible to the tester.

While Test::Output requires Test::Tester during installation, this requirement is only for it's own tests, not for what it's testing. One of the main ideas behind Test::Output is to make it as self contained as possible so it can be included with other's modules. As of this release the only requirement is to include Test::Output::Tie along with it.

Test::Output ties STDOUT and STDERR using Test::Output::Tie.

All functions are exported.

TESTS

STDOUT

stdout_is
stdout_isnt
stdout_is  ( $coderef, $expected, 'description' );
stdout_isnt( $coderef, $expected, 'description' );

stdout_is() captures output sent to STDOUT from $coderef and compares it against $expected. The test passes if equal.

stdout_isnt() passes if STDOUT is not equal to $expected.

stdout_like
stdout_unlike
stdout_like  ( $coderef, qr/$expected/, 'description' );
stdout_unlike( $coderef, qr/$expected/, 'description' );

stdout_like() captures the output sent to STDOUT from $coderef and compares it to the regex in $expected. The test passes if the regex matches.

stdout_unlike() passes if STDOUT does not match the regex.

STDERR

stderr_is
stderr_isnt
stderr_is  ( $coderef, $expected, 'description' );
stderr_isnt( $coderef, $expected, 'description' );

stderr_is() is similar to stdout_is, except that it captures STDERR. The test passes if STDERR from $coderef equals $expected.

stderr_isnt() passes if STDERR is not equal to $expected.

stderr_like
stderr_unlike
stderr_like  ( $coderef, qr/$expected/, 'description' );
stderr_unlike( $coderef, qr/$expected/, 'description' );

stderr_like() is similar to stdout_like() except that it compares the regex $expected to STDERR captured from $codref. The test passes if the regex matches.

stderr_unlike() passes if STDERR does not match the regex.

OUTPUT

output_is
output_isnt
output_is  ( $coderef, $expected_stdout, $expected_stderr, 'description' );
output_isnt( $coderef, $expected_stdout, $expected_stderr, 'description' );

The output_is() function is a combination of the stdout_is() and stderr_is() functions. For example:

output_is(sub {print "foo"; print STDERR "bar";},'foo','bar');

is functionally equivalent to

stdout_is(sub {print "foo";},'foo') 
  && stderr_is(sub {print STDERR "bar";'bar');

except that $coderef is only executed once.

Unlike, stdout_is() and stderr_is() which ignore STDERR and STDOUT repectively, output_is() requires both STDOUT and STDERR to match in order to pass. Setting either $expected_stdout or $expected_stderr to undef ignores STDOUT or STDERR respectively.

output_is(sub {print "foo"; print STDERR "bar";},'foo',undef);

is the same as

stdout_is(sub {print "foo";},'foo')

output_isnt() provides the opposite function of output_is(). It is a combination of stdout_isnt() and stderr_isnt().

output_isnt(sub {print "foo"; print STDERR "bar";},'bar','foo');

is functionally equivalent to

stdout_is(sub {print "foo";},'bar') 
  && stderr_is(sub {print STDERR "bar";'foo');

As with output_is(), setting either $expected_stdout or $expected_stderr to undef ignores the output to that facility.

output_isnt(sub {print "foo"; print STDERR "bar";},undef,'foo');

is the same as

stderr_is(sub {print STDERR "bar";},'foo')
output_like
output_unlike
output_like  ( $coderef, $regex_stdout, $regex_stderr, 'description' );
output_unlike( $coderef, $regex_stdout, $regex_stderr, 'description' );

output_like() and output_unlike() follow the same principles as output_is() and output_isnt() except they use a regular expression for matching.

output_like() attempts to match $regex_stdout and $regex_stderr against STDOUT and STDERR produced by $coderef. The test passes if both match.

output_like(sub {print "foo"; print STDERR "bar";},qr/foo/,qr/bar/);

The above test is successful.

Like output_is(), setting either $regex_stdout or $regex_stderr to undef ignores the output to that facility.

output_like(sub {print "foo"; print STDERR "bar";},qr/foo/,undef);

is the same as

stdout_like(sub {print "foo"; print STDERR "bar";},qr/foo/);

output_unlike() test pass if output from $coderef doesn't match $regex_stdout and $regex_stderr.

FUNCTIONS

stdout_from

my $stdout = stdout_from($coderef)

stdout_from() executes $coderef and captures STDOUT.

stderr_from

my $stderr = stderr_from($coderef)

stderr_from() executes $coderef and captures STDERR.

output_from

my ($stdout, $stderr) = output_from($coderef)

output_from() executes $coderef one time capturing both STDOUT and STDERR.

AUTHOR

Shawn Sorichetti, <ssoriche@coloredblocks.net>

BUGS

Please report any bugs or feature requests to bug-test-output@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

Thanks to chromatic whose TieOut.pm was the basis for capturing output.

Also thanks to rjbs for his help cleaning the documention

COPYRIGHT & LICENSE

Copyright 2005 Shawn Sorichetti, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.