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 compares
99           the regex $expected to "STDERR" captured from $codref. The test
100           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 "STDOUT".
113           This is equivalent to UNIXs "2>&1". The test passes if the combined
114           "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 compares
127           a regex ("$expected)" to "STDOUT" and "STDERR" captured from
128           $codref. The test passes if the regex matches.
129
130           combined_unlike() passes if the combined "STDOUT" and "STDERR" does
131           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() and
142           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 STDOUT
154           respectively, output_is() requires both "STDOUT" and "STDERR" to
155           match in order to pass. Setting either $expected_stdout or
156           $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 is
166           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 expression
193           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 to
204           "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                      2023-01-20                   Test::Output(3)
Impressum