Test::Builder::Tester(3pm)

1Test::Builder::Tester(3U)ser Contributed Perl DocumentatiToenst::Builder::Tester(3)
2
3
4

NAME

6       Test::Builder::Tester - test testsuites that have been built with
7       Test::Builder
8

SYNOPSIS

10           use Test::Builder::Tester tests => 1;
11           use Test::More;
12
13           test_out("not ok 1 - foo");
14           test_fail(+1);
15           fail("foo");
16           test_test("fail works");
17

DESCRIPTION

19       A module that helps you test testing modules that are built with
20       Test::Builder.
21
22       The testing system is designed to be used by performing a three step
23       process for each test you wish to test.  This process starts with using
24       "test_out" and "test_err" in advance to declare what the testsuite you
25       are testing will output with Test::Builder to stdout and stderr.
26
27       You then can run the test(s) from your test suite that call
28       Test::Builder.  At this point the output of Test::Builder is safely
29       captured by Test::Builder::Tester rather than being interpreted as real
30       test output.
31
32       The final stage is to call "test_test" that will simply compare what
33       you predeclared to what Test::Builder actually outputted, and report
34       the results back with a "ok" or "not ok" (with debugging) to the normal
35       output.
36
37   Functions
38       These are the six methods that are exported as default.
39
40       test_out
41       test_err
42           Procedures for predeclaring the output that your test suite is
43           expected to produce until "test_test" is called.  These procedures
44           automatically assume that each line terminates with "\n".  So
45
46              test_out("ok 1","ok 2");
47
48           is the same as
49
50              test_out("ok 1\nok 2");
51
52           which is even the same as
53
54              test_out("ok 1");
55              test_out("ok 2");
56
57           Once "test_out" or "test_err" (or "test_fail" or "test_diag") have
58           been called, all further output from Test::Builder will be captured
59           by Test::Builder::Tester.  This means that you will not be able
60           perform further tests to the normal output in the normal way until
61           you call "test_test" (well, unless you manually meddle with the
62           output filehandles)
63
64       test_fail
65           Because the standard failure message that Test::Builder produces
66           whenever a test fails will be a common occurrence in your test
67           error output, and because it has changed between Test::Builder
68           versions, rather than forcing you to call "test_err" with the
69           string all the time like so
70
71               test_err("# Failed test ($0 at line ".line_num(+1).")");
72
73           "test_fail" exists as a convenience function that can be called
74           instead.  It takes one argument, the offset from the current line
75           that the line that causes the fail is on.
76
77               test_fail(+1);
78
79           This means that the example in the synopsis could be rewritten more
80           simply as:
81
82              test_out("not ok 1 - foo");
83              test_fail(+1);
84              fail("foo");
85              test_test("fail works");
86
87       test_diag
88           As most of the remaining expected output to the error stream will
89           be created by Test::Builder's "diag" function,
90           Test::Builder::Tester provides a convenience function "test_diag"
91           that you can use instead of "test_err".
92
93           The "test_diag" function prepends comment hashes and spacing to the
94           start and newlines to the end of the expected output passed to it
95           and adds it to the list of expected error output.  So, instead of
96           writing
97
98              test_err("# Couldn't open file");
99
100           you can write
101
102              test_diag("Couldn't open file");
103
104           Remember that Test::Builder's diag function will not add newlines
105           to the end of output and test_diag will. So to check
106
107              Test::Builder->new->diag("foo\n","bar\n");
108
109           You would do
110
111             test_diag("foo","bar")
112
113           without the newlines.
114
115       test_test
116           Actually performs the output check testing the tests, comparing the
117           data (with "eq") that we have captured from Test::Builder against
118           what was declared with "test_out" and "test_err".
119
120           This takes name/value pairs that effect how the test is run.
121
122           title (synonym 'name', 'label')
123               The name of the test that will be displayed after the "ok" or
124               "not ok".
125
126           skip_out
127               Setting this to a true value will cause the test to ignore if
128               the output sent by the test to the output stream does not match
129               that declared with "test_out".
130
131           skip_err
132               Setting this to a true value will cause the test to ignore if
133               the output sent by the test to the error stream does not match
134               that declared with "test_err".
135
136           As a convenience, if only one argument is passed then this argument
137           is assumed to be the name of the test (as in the above examples.)
138
139           Once "test_test" has been run test output will be redirected back
140           to the original filehandles that Test::Builder was connected to
141           (probably STDOUT and STDERR,) meaning any further tests you run
142           will function normally and cause success/errors for Test::Harness.
143
144       line_num
145           A utility function that returns the line number that the function
146           was called on.  You can pass it an offset which will be added to
147           the result.  This is very useful for working out the correct text
148           of diagnostic functions that contain line numbers.
149
150           Essentially this is the same as the "__LINE__" macro, but the
151           "line_num(+3)" idiom is arguably nicer.
152
153       In addition to the six exported functions there exists one function
154       that can only be accessed with a fully qualified function call.
155
156       color
157           When "test_test" is called and the output that your tests generate
158           does not match that which you declared, "test_test" will print out
159           debug information showing the two conflicting versions.  As this
160           output itself is debug information it can be confusing which part
161           of the output is from "test_test" and which was the original output
162           from your original tests.  Also, it may be hard to spot things like
163           extraneous whitespace at the end of lines that may cause your test
164           to fail even though the output looks similar.
165
166           To assist you "test_test" can colour the background of the debug
167           information to disambiguate the different types of output. The
168           debug output will have its background coloured green and red.  The
169           green part represents the text which is the same between the
170           executed and actual output, the red shows which part differs.
171
172           The "color" function determines if colouring should occur or not.
173           Passing it a true or false value will enable or disable colouring
174           respectively, and the function called with no argument will return
175           the current setting.
176
177           To enable colouring from the command line, you can use the
178           Text::Builder::Tester::Color module like so:
179
180              perl -Mlib=Text::Builder::Tester::Color test.t
181
182           Or by including the Test::Builder::Tester::Color module directly in
183           the PERL5LIB.
184

BUGS

186       Test::Builder::Tester does not handle plans well. It has never done
187       anything special with plans. This means that plans from outside
188       Test::Builder::Tester will effect Test::Builder::Tester, worse plans
189       when using Test::Builder::Tester will effect overall testing. At this
190       point there are no plans to fix this bug as people have come to depend
191       on it, and Test::Builder::Tester is now discouraged in favor of
192       "Test2::API::intercept()". See
193       <https://github.com/Test-More/test-more/issues/667>
194
195       Calls "Test::Builder->no_ending" turning off the ending tests.  This is
196       needed as otherwise it will trip out because we've run more tests than
197       we strictly should have and it'll register any failures we had that we
198       were testing for as real failures.
199
200       The color function doesn't work unless Term::ANSIColor is compatible
201       with your terminal. Additionally, Win32::Console::ANSI must be
202       installed on windows platforms for color output.
203
204       Bugs (and requests for new features) can be reported to the author
205       though GitHub: <https://github.com/Test-More/test-more/issues>
206

AUTHOR

208       Copyright Mark Fowler <mark@twoshortplanks.com> 2002, 2004.
209
210       Some code taken from Test::More and Test::Catch, written by Michael G
211       Schwern <schwern@pobox.com>.  Hence, those parts Copyright Micheal G
212       Schwern 2001.  Used and distributed with permission.
213
214       This program is free software; you can redistribute it and/or modify it
215       under the same terms as Perl itself.
216

MAINTAINERS

218       Chad Granum <exodist@cpan.org>
219

NOTES

221       Thanks to Richard Clamp <richardc@unixbeard.net> for letting me use his
222       testing system to try this module out on.
223