Debian Codegraph @

upstream/debian-unstable/man3/Test::Builder::Tester.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Test::Builder::Tester 3perl"
58 .TH Test::Builder::Tester 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test::Builder::Tester \- test testsuites that have been built with
65 Test::Builder
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 2
69 \& use Test::Builder::Tester tests => 1;
70 \& use Test::More;
71 \&
72 \& test_out("not ok 1 \- foo");
73 \& test_fail(+1);
74 \& fail("foo");
75 \& test_test("fail works");
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 A module that helps you test testing modules that are built with
80 Test::Builder.
81 .PP
82 The testing system is designed to be used by performing a three step
83 process for each test you wish to test. This process starts with using
84 \&\f(CW\*(C`test_out\*(C'\fR and \f(CW\*(C`test_err\*(C'\fR in advance to declare what the testsuite you
85 are testing will output with Test::Builder to stdout and stderr.
86 .PP
87 You then can run the test(s) from your test suite that call
88 Test::Builder. At this point the output of Test::Builder is
89 safely captured by Test::Builder::Tester rather than being
90 interpreted as real test output.
91 .PP
92 The final stage is to call \f(CW\*(C`test_test\*(C'\fR that will simply compare what you
93 predeclared to what Test::Builder actually outputted, and report the
94 results back with a "ok" or "not ok" (with debugging) to the normal
95 output.
96 .SS Functions
97 .IX Subsection "Functions"
98 These are the six methods that are exported as default.
99 .IP test_out 4
100 .IX Item "test_out"
101 .PD 0
102 .IP test_err 4
103 .IX Item "test_err"
104 .PD
105 Procedures for predeclaring the output that your test suite is
106 expected to produce until \f(CW\*(C`test_test\*(C'\fR is called. These procedures
107 automatically assume that each line terminates with "\en". So
108 .Sp
109 .Vb 1
110 \& test_out("ok 1","ok 2");
111 .Ve
112 .Sp
113 is the same as
114 .Sp
115 .Vb 1
116 \& test_out("ok 1\enok 2");
117 .Ve
118 .Sp
119 which is even the same as
120 .Sp
121 .Vb 2
122 \& test_out("ok 1");
123 \& test_out("ok 2");
124 .Ve
125 .Sp
126 Once \f(CW\*(C`test_out\*(C'\fR or \f(CW\*(C`test_err\*(C'\fR (or \f(CW\*(C`test_fail\*(C'\fR or \f(CW\*(C`test_diag\*(C'\fR) have
127 been called, all further output from Test::Builder will be
128 captured by Test::Builder::Tester. This means that you will not
129 be able perform further tests to the normal output in the normal way
130 until you call \f(CW\*(C`test_test\*(C'\fR (well, unless you manually meddle with the
131 output filehandles)
132 .IP test_fail 4
133 .IX Item "test_fail"
134 Because the standard failure message that Test::Builder produces
135 whenever a test fails will be a common occurrence in your test error
136 output, and because it has changed between Test::Builder versions, rather
137 than forcing you to call \f(CW\*(C`test_err\*(C'\fR with the string all the time like
138 so
139 .Sp
140 .Vb 1
141 \& test_err("# Failed test ($0 at line ".line_num(+1).")");
142 .Ve
143 .Sp
144 \&\f(CW\*(C`test_fail\*(C'\fR exists as a convenience function that can be called
145 instead. It takes one argument, the offset from the current line that
146 the line that causes the fail is on.
147 .Sp
148 .Vb 1
149 \& test_fail(+1);
150 .Ve
151 .Sp
152 This means that the example in the synopsis could be rewritten
153 more simply as:
154 .Sp
155 .Vb 4
156 \& test_out("not ok 1 \- foo");
157 \& test_fail(+1);
158 \& fail("foo");
159 \& test_test("fail works");
160 .Ve
161 .IP test_diag 4
162 .IX Item "test_diag"
163 As most of the remaining expected output to the error stream will be
164 created by Test::Builder's \f(CW\*(C`diag\*(C'\fR function, Test::Builder::Tester
165 provides a convenience function \f(CW\*(C`test_diag\*(C'\fR that you can use instead of
166 \&\f(CW\*(C`test_err\*(C'\fR.
167 .Sp
168 The \f(CW\*(C`test_diag\*(C'\fR function prepends comment hashes and spacing to the
169 start and newlines to the end of the expected output passed to it and
170 adds it to the list of expected error output. So, instead of writing
171 .Sp
172 .Vb 1
173 \& test_err("# Couldn\*(Aqt open file");
174 .Ve
175 .Sp
176 you can write
177 .Sp
178 .Vb 1
179 \& test_diag("Couldn\*(Aqt open file");
180 .Ve
181 .Sp
182 Remember that Test::Builder's diag function will not add newlines to
183 the end of output and test_diag will. So to check
184 .Sp
185 .Vb 1
186 \& Test::Builder\->new\->diag("foo\en","bar\en");
187 .Ve
188 .Sp
189 You would do
190 .Sp
191 .Vb 1
192 \& test_diag("foo","bar")
193 .Ve
194 .Sp
195 without the newlines.
196 .IP test_test 4
197 .IX Item "test_test"
198 Actually performs the output check testing the tests, comparing the
199 data (with \f(CW\*(C`eq\*(C'\fR) that we have captured from Test::Builder against
200 what was declared with \f(CW\*(C`test_out\*(C'\fR and \f(CW\*(C`test_err\*(C'\fR.
201 .Sp
202 This takes name/value pairs that effect how the test is run.
203 .RS 4
204 .IP "title (synonym 'name', 'label')" 4
205 .IX Item "title (synonym 'name', 'label')"
206 The name of the test that will be displayed after the \f(CW\*(C`ok\*(C'\fR or \f(CW\*(C`not
207 ok\*(C'\fR.
208 .IP skip_out 4
209 .IX Item "skip_out"
210 Setting this to a true value will cause the test to ignore if the
211 output sent by the test to the output stream does not match that
212 declared with \f(CW\*(C`test_out\*(C'\fR.
213 .IP skip_err 4
214 .IX Item "skip_err"
215 Setting this to a true value will cause the test to ignore if the
216 output sent by the test to the error stream does not match that
217 declared with \f(CW\*(C`test_err\*(C'\fR.
218 .RE
219 .RS 4
220 .Sp
221 As a convenience, if only one argument is passed then this argument
222 is assumed to be the name of the test (as in the above examples.)
223 .Sp
224 Once \f(CW\*(C`test_test\*(C'\fR has been run test output will be redirected back to
225 the original filehandles that Test::Builder was connected to
226 (probably STDOUT and STDERR,) meaning any further tests you run
227 will function normally and cause success/errors for Test::Harness.
228 .RE
229 .IP line_num 4
230 .IX Item "line_num"
231 A utility function that returns the line number that the function was
232 called on. You can pass it an offset which will be added to the
233 result. This is very useful for working out the correct text of
234 diagnostic functions that contain line numbers.
235 .Sp
236 Essentially this is the same as the \f(CW\*(C`_\|_LINE_\|_\*(C'\fR macro, but the
237 \&\f(CWline_num(+3)\fR idiom is arguably nicer.
238 .PP
239 In addition to the six exported functions there exists one
240 function that can only be accessed with a fully qualified function
241 call.
242 .IP color 4
243 .IX Item "color"
244 When \f(CW\*(C`test_test\*(C'\fR is called and the output that your tests generate
245 does not match that which you declared, \f(CW\*(C`test_test\*(C'\fR will print out
246 debug information showing the two conflicting versions. As this
247 output itself is debug information it can be confusing which part of
248 the output is from \f(CW\*(C`test_test\*(C'\fR and which was the original output from
249 your original tests. Also, it may be hard to spot things like
250 extraneous whitespace at the end of lines that may cause your test to
251 fail even though the output looks similar.
252 .Sp
253 To assist you \f(CW\*(C`test_test\*(C'\fR can colour the background of the debug
254 information to disambiguate the different types of output. The debug
255 output will have its background coloured green and red. The green
256 part represents the text which is the same between the executed and
257 actual output, the red shows which part differs.
258 .Sp
259 The \f(CW\*(C`color\*(C'\fR function determines if colouring should occur or not.
260 Passing it a true or false value will enable or disable colouring
261 respectively, and the function called with no argument will return the
262 current setting.
263 .Sp
264 To enable colouring from the command line, you can use the
265 Text::Builder::Tester::Color module like so:
266 .Sp
267 .Vb 1
268 \& perl \-Mlib=Text::Builder::Tester::Color test.t
269 .Ve
270 .Sp
271 Or by including the Test::Builder::Tester::Color module directly in
272 the PERL5LIB.
273 .SH BUGS
274 .IX Header "BUGS"
275 Test::Builder::Tester does not handle plans well. It has never done anything
276 special with plans. This means that plans from outside Test::Builder::Tester
277 will effect Test::Builder::Tester, worse plans when using Test::Builder::Tester
278 will effect overall testing. At this point there are no plans to fix this bug
279 as people have come to depend on it, and Test::Builder::Tester is now
280 discouraged in favor of \f(CWTest2::API::intercept()\fR. See
281 <https://github.com/Test\-More/test\-more/issues/667>
282 .PP
283 Calls \f(CW\*(C`Test::Builder\->no_ending\*(C'\fR turning off the ending tests.
284 This is needed as otherwise it will trip out because we've run more
285 tests than we strictly should have and it'll register any failures we
286 had that we were testing for as real failures.
287 .PP
288 The color function doesn't work unless Term::ANSIColor is
289 compatible with your terminal. Additionally, Win32::Console::ANSI
290 must be installed on windows platforms for color output.
291 .PP
292 Bugs (and requests for new features) can be reported to the author
293 though GitHub:
294 <https://github.com/Test\-More/test\-more/issues>
295 .SH AUTHOR
296 .IX Header "AUTHOR"
297 Copyright Mark Fowler <[email protected]> 2002, 2004.
298 .PP
299 Some code taken from Test::More and Test::Catch, written by
300 Michael G Schwern <[email protected]>. Hence, those parts
301 Copyright Micheal G Schwern 2001. Used and distributed with
302 permission.
303 .PP
304 This program is free software; you can redistribute it
305 and/or modify it under the same terms as Perl itself.
306 .SH MAINTAINERS
307 .IX Header "MAINTAINERS"
308 .IP "Chad Granum <[email protected]>" 4
309 .IX Item "Chad Granum <[email protected]>"
310 .SH NOTES
311 .IX Header "NOTES"
312 Thanks to Richard Clamp <[email protected]> for letting
313 me use his testing system to try this module out on.
314 .SH "SEE ALSO"
315 .IX Header "SEE ALSO"
316 Test::Builder, Test::Builder::Tester::Color, Test::More.