1Test::Output(3)       User Contributed Perl Documentation      Test::Output(3)
2
3
4

NAME

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

VERSION

9       Version 0.12
10

SYNOPSIS

12           use Test::More tests => 4;
13           use Test::Output;
14
15           sub writer {
16             print "Write out.\n";
17             print STDERR "Error out.\n";
18           }
19
20           stdout_is(\&writer,"Write out.\n",'Test STDOUT');
21
22           stderr_isnt(\&writer,"No error out.\n",'Test STDERR');
23
24           combined_is(
25                       \&writer,
26                       "Write out.\nError out.\n",
27                       'Test STDOUT & STDERR combined'
28                      );
29
30           output_is(
31                     \&writer,
32                     "Write out.\n",
33                     "Error out.\n",
34                     'Test STDOUT & STDERR'
35                   );
36
37          # Use bare blocks.
38
39          stdout_is { print "test" } "test" "Test STDOUT";
40          stderr_isnt { print "bad test" } "test" "Test STDERR";
41          output_is { print 'STDOUT'; print STDERR 'STDERR' }
42            "STDOUT", "STDERR", "Test output";
43

DESCRIPTION

45       Test::Output provides a simple interface for testing output sent to
46       STDOUT or STDERR. A number of different utilities are included to try
47       and be as flexible as possible to the tester.
48
49       Originally this module was designed not to have external requirements,
50       however, the features provided by Sub::Exporter over what Exporter
51       provides is just to great to pass up.
52
53       Test::Output ties STDOUT and STDERR using Test::Output::Tie.
54

TESTS

56   STDOUT
57       stdout_is
58       stdout_isnt
59              stdout_is  ( $coderef, $expected, 'description' );
60              stdout_is    { ... } $expected, 'description';
61              stdout_isnt( $coderef, $expected, 'description' );
62              stdout_isnt  { ... } $expected, 'description';
63
64           stdout_is() captures output sent to STDOUT from $coderef and
65           compares it against $expected. The test passes if equal.
66
67           stdout_isnt() passes if STDOUT is not equal to $expected.
68
69       stdout_like
70       stdout_unlike
71              stdout_like  ( $coderef, qr/$expected/, 'description' );
72              stdout_like    { ... } qr/$expected/, 'description';
73              stdout_unlike( $coderef, qr/$expected/, 'description' );
74              stdout_unlike  { ... } qr/$expected/, 'description';
75
76           stdout_like() captures the output sent to STDOUT from $coderef and
77           compares it to the regex in $expected. The test passes if the regex
78           matches.
79
80           stdout_unlike() passes if STDOUT does not match the regex.
81
82   STDERR
83       stderr_is
84       stderr_isnt
85              stderr_is  ( $coderef, $expected, 'description' );
86              stderr_is    {... } $expected, 'description';
87              stderr_isnt( $coderef, $expected, 'description' );
88              stderr_isnt  {... } $expected, 'description';
89
90           stderr_is() is similar to stdout_is, except that it captures
91           STDERR. The test passes if STDERR from $coderef equals $expected.
92
93           stderr_isnt() passes if STDERR is not equal to $expected.
94
95       stderr_like
96       stderr_unlike
97              stderr_like  ( $coderef, qr/$expected/, 'description' );
98              stderr_like   { ...} qr/$expected/, 'description';
99              stderr_unlike( $coderef, qr/$expected/, 'description' );
100              stderr_unlike  { ...} qr/$expected/, 'description';
101
102           stderr_like() is similar to stdout_like() except that it compares
103           the regex $expected to STDERR captured from $codref. The test
104           passes if the regex matches.
105
106           stderr_unlike() passes if STDERR does not match the regex.
107
108   COMBINED OUTPUT
109       combined_is
110       combined_isnt
111              combined_is   ( $coderef, $expected, 'description' );
112              combined_is   {... } $expected, 'description';
113              combined_isnt ( $coderef, $expected, 'description' );
114              combined_isnt {... } $expected, 'description';
115
116           combined_is() directs STDERR to STDOUT then captures STDOUT. This
117           is equivalent to UNIXs 2>&1. The test passes if the combined STDOUT
118           and STDERR from $coderef equals $expected.
119
120           combined_isnt() passes if combined STDOUT and STDERR are not equal
121           to $expected.
122
123       combined_like
124       combined_unlike
125              combined_like   ( $coderef, qr/$expected/, 'description' );
126              combined_like   { ...} qr/$expected/, 'description';
127              combined_unlike ( $coderef, qr/$expected/, 'description' );
128              combined_unlike { ...} qr/$expected/, 'description';
129
130           combined_like() is similar to combined_is() except that it compares
131           a regex ($expected) to STDOUT and STDERR captured from $codref. The
132           test passes if the regex matches.
133
134           combined_unlike() passes if the combined STDOUT and STDERR does not
135           match the regex.
136
137   OUTPUT
138       output_is
139       output_isnt
140              output_is  ( $coderef, $expected_stdout, $expected_stderr, 'description' );
141              output_is    {... } $expected_stdout, $expected_stderr, 'description';
142              output_isnt( $coderef, $expected_stdout, $expected_stderr, 'description' );
143              output_isnt  {... } $expected_stdout, $expected_stderr, 'description';
144
145           The output_is() function is a combination of the stdout_is() and
146           stderr_is() functions. For example:
147
148             output_is(sub {print "foo"; print STDERR "bar";},'foo','bar');
149
150           is functionally equivalent to
151
152             stdout_is(sub {print "foo";},'foo')
153               && stderr_is(sub {print STDERR "bar";'bar');
154
155           except that $coderef is only executed once.
156
157           Unlike, stdout_is() and stderr_is() which ignore STDERR and STDOUT
158           repectively, output_is() requires both STDOUT and STDERR to match
159           in order to pass. Setting either $expected_stdout or
160           $expected_stderr to "undef" ignores STDOUT or STDERR respectively.
161
162             output_is(sub {print "foo"; print STDERR "bar";},'foo',undef);
163
164           is the same as
165
166             stdout_is(sub {print "foo";},'foo')
167
168           output_isnt() provides the opposite function of output_is(). It is
169           a combination of stdout_isnt() and stderr_isnt().
170
171             output_isnt(sub {print "foo"; print STDERR "bar";},'bar','foo');
172
173           is functionally equivalent to
174
175             stdout_is(sub {print "foo";},'bar')
176               && stderr_is(sub {print STDERR "bar";'foo');
177
178           As with output_is(), setting either $expected_stdout or
179           $expected_stderr to "undef" ignores the output to that facility.
180
181             output_isnt(sub {print "foo"; print STDERR "bar";},undef,'foo');
182
183           is the same as
184
185             stderr_is(sub {print STDERR "bar";},'foo')
186
187       output_like
188       output_unlike
189             output_like  ( $coderef, $regex_stdout, $regex_stderr, 'description' );
190             output_like  { ... } $regex_stdout, $regex_stderr, 'description';
191             output_unlike( $coderef, $regex_stdout, $regex_stderr, 'description' );
192             output_unlike { ... } $regex_stdout, $regex_stderr, 'description';
193
194           output_like() and output_unlike() follow the same principles as
195           output_is() and output_isnt() except they use a regular expression
196           for matching.
197
198           output_like() attempts to match $regex_stdout and $regex_stderr
199           against STDOUT and STDERR produced by $coderef. The test passes if
200           both match.
201
202             output_like(sub {print "foo"; print STDERR "bar";},qr/foo/,qr/bar/);
203
204           The above test is successful.
205
206           Like output_is(), setting either $regex_stdout or $regex_stderr to
207           "undef" ignores the output to that facility.
208
209             output_like(sub {print "foo"; print STDERR "bar";},qr/foo/,undef);
210
211           is the same as
212
213             stdout_like(sub {print "foo"; print STDERR "bar";},qr/foo/);
214
215           output_unlike() test pass if output from $coderef doesn't match
216           $regex_stdout and $regex_stderr.
217

EXPORTS

219       By default, all tests are exported, however with the switch to
220       Sub::Exporter export groups are now available to better limit imports.
221
222       To import tests for STDOUT:
223
224         use Test::Output qw(:stdout);
225
226       To import tests STDERR:
227
228         use Test::Output qw(:stderr);
229
230       To import just the functions:
231
232         use Test::Output qw(:functions);
233
234       And to import all tests:
235
236         use Test::Output;
237
238       The following is a list of group names and which functions are
239       exported:
240
241       stdout
242           stdout_is stdout_isnt stdout_like stdout_unlike
243
244       stderr
245           stderr_is stderr_isnt stderr_like stderr_unlike
246
247       output
248           output_is output_isnt output_like output_unlike
249
250       combined
251           combined_is combined_isnt combined_like combined_unlike
252
253       tests
254           All of the above, this is the default when no options are given.
255
256       Sub::Exporter allows for many other options, I encourage reading its
257       documentation.
258

FUNCTIONS

260   stdout_from
261         my $stdout = stdout_from($coderef)
262         my $stdout = stdout_from { ... };
263
264       stdout_from() executes $coderef and captures STDOUT.
265
266   stderr_from
267         my $stderr = stderr_from($coderef)
268         my $stderr = stderr_from { ... };
269
270       stderr_from() executes $coderef and captures STDERR.
271
272   output_from
273         my ($stdout, $stderr) = output_from($coderef)
274         my ($stdout, $stderr) = output_from {...};
275
276       output_from() executes $coderef one time capturing both STDOUT and
277       STDERR.
278
279   combined_from
280         my $combined = combined_from($coderef);
281         my $combined = combined_from {...};
282
283       combined_from() executes $coderef one time combines STDOUT and STDERR,
284       and captures them. combined_from() is equivalent to using 2>&1 in UNIX.
285

AUTHOR

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

SOURCE AVAILABILITY

290       This module is in Github:
291
292       "/github.com/ssoriche/test-output/tree/master"" in <a
293       href="http:http://github.com/ssoriche/test-output/tree/master</a>>
294

BUGS

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

ACKNOWLEDGEMENTS

302       Thanks to chromatic whose TieOut.pm was the basis for capturing output.
303
304       Also thanks to rjbs for his help cleaning the documention, and pushing
305       me to Sub::Exporter.
306
307       Thanks to David Wheeler for providing code block support and tests.
308
309       Thanks to Michael G Schwern for the solution to combining STDOUT and
310       STDERR.
311

313       Copyright 2005 Shawn Sorichetti, All Rights Reserved.
314
315       This program is free software; you can redistribute it and/or modify it
316       under the same terms as Perl itself.
317
318
319
320perl v5.12.0                      2008-10-25                   Test::Output(3)
Impressum