Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test::Builder::Tester.3pm

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