Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::Output(3)	      User Contributed Perl Documentation      Test::Output(3)

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

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');

	   combined_is(
		       \&writer,
		       "Write out.\nError out.\n",
		       'Test STDOUT & STDERR combined'
		      );

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

	  # Use	bare blocks.

	  stdout_is { print "test" } "test", "Test STDOUT";
	  stderr_isnt {	print "bad test" } "test", "Test STDERR";
	  output_is { print 'STDOUT'; print STDERR 'STDERR' }
	    "STDOUT", "STDERR",	"Test output";

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

       Likewise, Capture::Tiny provides	a much more robust capture mechanism
       without than the	original Test::Output::Tie.

TESTS
   STDOUT
       stdout_is
       stdout_isnt
	      stdout_is	 ( $coderef, $expected,	'description' );
	      stdout_is	   { ... } $expected, 'description';
	      stdout_isnt( $coderef, $expected,	'description' );
	      stdout_isnt  { ... } $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_like    { ... } qr/$expected/, 'description';
	      stdout_unlike( $coderef, qr/$expected/, 'description' );
	      stdout_unlike  { ... } 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_is	   {...	} $expected, 'description';

	      stderr_isnt( $coderef, $expected,	'description' );
	      stderr_isnt  {...	} $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_like   { ...} qr/$expected/, 'description';
	      stderr_unlike( $coderef, qr/$expected/, 'description' );
	      stderr_unlike  { ...} 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.

   COMBINED OUTPUT
       combined_is
       combined_isnt
	      combined_is   ( $coderef,	$expected, 'description' );
	      combined_is   {... } $expected, 'description';
	      combined_isnt ( $coderef,	$expected, 'description' );
	      combined_isnt {... } $expected, 'description';

	   "combined_is()" directs "STDERR" to "STDOUT"	then captures
	   "STDOUT". This is equivalent	to UNIXs "2>&1". The test passes if
	   the combined	"STDOUT" and "STDERR" from $coderef equals $expected.

	   "combined_isnt()" passes if combined	"STDOUT" and "STDERR" are not
	   equal to $expected.

       combined_like
       combined_unlike
	      combined_like   (	$coderef, qr/$expected/, 'description' );
	      combined_like   {	...} qr/$expected/, 'description';
	      combined_unlike (	$coderef, qr/$expected/, 'description' );
	      combined_unlike {	...} qr/$expected/, 'description';

	   "combined_like()" is	similar	to "combined_is()" except that it
	   compares a regex ("$expected)" to "STDOUT" and "STDERR" captured
	   from	$codref. The test passes if the	regex matches.

	   "combined_unlike()" passes if the combined "STDOUT" and "STDERR"
	   does	not match the regex.

   OUTPUT
       output_is
       output_isnt
	      output_is	 ( $coderef, $expected_stdout, $expected_stderr, 'description' );
	      output_is	   {...	} $expected_stdout, $expected_stderr, 'description';
	      output_isnt( $coderef, $expected_stdout, $expected_stderr, 'description' );
	      output_isnt  {...	} $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 respectively,	"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_like  { ...	} $regex_stdout, $regex_stderr,	'description';
	     output_unlike( $coderef, $regex_stdout, $regex_stderr, 'description' );
	     output_unlike { ... } $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.

EXPORTS
       By default, all subroutines are exported	by default.

       o   :stdout - the subs with "stdout" in the name.

       o   :stderr - the subs with "stderr" in the name.

       o   :functions -	the subs with "_from" at the end.

       o   :output - the subs with "output" in the name.

       o   :combined - the subs	with "combined"	in the name.

       o   :tests - everything that outputs TAP

       o   :all	- everything (which is the same	as the default)

FUNCTIONS
   stdout_from
	 my $stdout = stdout_from($coderef)
	 my $stdout = stdout_from { ...	};

       stdout_from() executes $coderef and captures STDOUT.

   stderr_from
	 my $stderr = stderr_from($coderef)
	 my $stderr = stderr_from { ...	};

       "stderr_from()" executes	$coderef and captures "STDERR".

   output_from
	 my ($stdout, $stderr) = output_from($coderef)
	 my ($stdout, $stderr) = output_from {...};

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

   combined_from
	 my $combined =	combined_from($coderef);
	 my $combined =	combined_from {...};

       "combined_from()" executes $coderef one time combines "STDOUT" and
       "STDERR", and captures them. "combined_from()" is equivalent to using
       "2>&1" in UNIX.

AUTHOR
       Currently maintained by brian d foy, "bdfoy@cpan.org".

       Shawn Sorichetti, "<ssoriche@cpan.org>"

SOURCE AVAILABILITY
       This module is in Github:

	       http://github.com/briandfoy/test-output/tree/master

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 documentation, and
       pushing me to Sub::Exporter. (This feature has been removed since it
       uses none of Sub::Exporter's strengths).

       Thanks to David Wheeler for providing code block	support	and tests.

       Thanks to Michael G Schwern for the solution to combining "STDOUT" and
       "STDERR".

COPYRIGHT & LICENSE
       Copyright 2005-2013 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.

perl v5.32.1			  2017-03-29		       Test::Output(3)

NAME | SYNOPSIS | DESCRIPTION | TESTS | EXPORTS | FUNCTIONS | AUTHOR | SOURCE AVAILABILITY | BUGS | ACKNOWLEDGEMENTS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::Output&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help