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

SYNOPSIS

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

DESCRIPTION

42       Test::Output provides a simple interface for testing output sent to
43       "STDOUT" or "STDERR". A number of different utilities are included to
44       try and be as flexible as possible to the tester.
45
46       Likewise, Capture::Tiny provides a much more robust capture mechanism
47       without than the original Test::Output::Tie.
48

TESTS

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

EXPORTS

216       By default, all subroutines are exported by default.
217
218       •   :stdout - the subs with "stdout" in the name.
219
220       •   :stderr - the subs with "stderr" in the name.
221
222       •   :functions - the subs with "_from" at the end.
223
224       •   :output - the subs with "output" in the name.
225
226       •   :combined - the subs with "combined" in the name.
227
228       •   :tests - everything that outputs TAP
229
230       •   :all - everything (which is the same as the default)
231

FUNCTIONS

233   stdout_from
234         my $stdout = stdout_from($coderef)
235         my $stdout = stdout_from { ... };
236
237       stdout_from() executes $coderef and captures STDOUT.
238
239   stderr_from
240         my $stderr = stderr_from($coderef)
241         my $stderr = stderr_from { ... };
242
243       "stderr_from()" executes $coderef and captures "STDERR".
244
245   output_from
246         my ($stdout, $stderr) = output_from($coderef)
247         my ($stdout, $stderr) = output_from {...};
248
249       "output_from()" executes $coderef one time capturing both "STDOUT" and
250       "STDERR".
251
252   combined_from
253         my $combined = combined_from($coderef);
254         my $combined = combined_from {...};
255
256       "combined_from()" executes $coderef one time combines "STDOUT" and
257       "STDERR", and captures them. "combined_from()" is equivalent to using
258       "2>&1" in UNIX.
259

AUTHOR

261       Currently maintained by brian d foy, "bdfoy@cpan.org".
262
263       Shawn Sorichetti, "<ssoriche@cpan.org>"
264

SOURCE AVAILABILITY

266       This module is in Github:
267
268               http://github.com/briandfoy/test-output
269

BUGS

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

ACKNOWLEDGEMENTS

277       Thanks to chromatic whose TieOut.pm was the basis for capturing output.
278
279       Also thanks to rjbs for his help cleaning the documentation, and
280       pushing me to Sub::Exporter. (This feature has been removed since it
281       uses none of Sub::Exporter's strengths).
282
283       Thanks to David Wheeler for providing code block support and tests.
284
285       Thanks to Michael G Schwern for the solution to combining "STDOUT" and
286       "STDERR".
287

289       Copyright 2005-2021 Shawn Sorichetti, All Rights Reserved.
290
291       This module is licensed under the Artistic License 2.0.
292
293
294
295perl v5.36.0                      2022-07-22                   Test::Output(3)
Impressum