Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test::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::Tester 3pm"
61 .TH Test::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::Tester \- Ease testing test modules built with Test::Builder
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Test::Tester tests => 6;
72 \&
73 \& use Test::MyStyle;
74 \&
75 \& check_test(
76 \& sub {
77 \& is_mystyle_eq("this", "that", "not eq");
78 \& },
79 \& {
80 \& ok => 0, # expect this to fail
81 \& name => "not eq",
82 \& diag => "Expected: \*(Aqthis\*(Aq\enGot: \*(Aqthat\*(Aq",
83 \& }
84 \& );
85 .Ve
86 .PP
87 or
88 .PP
89 .Vb 1
90 \& use Test::Tester tests => 6;
91 \&
92 \& use Test::MyStyle;
93 \&
94 \& check_test(
95 \& sub {
96 \& is_mystyle_qr("this", "that", "not matching");
97 \& },
98 \& {
99 \& ok => 0, # expect this to fail
100 \& name => "not matching",
101 \& diag => qr/Expected: \*(Aqthis\*(Aq\es+Got: \*(Aqthat\*(Aq/,
102 \& }
103 \& );
104 .Ve
105 .PP
106 or
107 .PP
108 .Vb 1
109 \& use Test::Tester;
110 \&
111 \& use Test::More tests => 3;
112 \& use Test::MyStyle;
113 \&
114 \& my ($premature, @results) = run_tests(
115 \& sub {
116 \& is_database_alive("dbname");
117 \& }
118 \& );
119 \&
120 \& # now use Test::More::like to check the diagnostic output
121 \&
122 \& like($results[0]\->{diag}, "/^Database ping took \e\ed+ seconds$"/, "diag");
123 .Ve
124 .SH DESCRIPTION
125 .IX Header "DESCRIPTION"
126 If you have written a test module based on Test::Builder then Test::Tester
127 allows you to test it with the minimum of effort.
128 .SH "HOW TO USE (THE EASY WAY)"
129 .IX Header "HOW TO USE (THE EASY WAY)"
130 From version 0.08 Test::Tester no longer requires you to included anything
131 special in your test modules. All you need to do is
132 .PP
133 .Vb 1
134 \& use Test::Tester;
135 .Ve
136 .PP
137 in your test script \fBbefore\fR any other Test::Builder based modules and away
138 you go.
139 .PP
140 Other modules based on Test::Builder can be used to help with the
141 testing. In fact you can even use functions from your module to test
142 other functions from the same module (while this is possible it is
143 probably not a good idea, if your module has bugs, then
144 using it to test itself may give the wrong answers).
145 .PP
146 The easiest way to test is to do something like
147 .PP
148 .Vb 8
149 \& check_test(
150 \& sub { is_mystyle_eq("this", "that", "not eq") },
151 \& {
152 \& ok => 0, # we expect the test to fail
153 \& name => "not eq",
154 \& diag => "Expected: \*(Aqthis\*(Aq\enGot: \*(Aqthat\*(Aq",
155 \& }
156 \& );
157 .Ve
158 .PP
159 this will execute the is_mystyle_eq test, capturing its results and
160 checking that they are what was expected.
161 .PP
162 You may need to examine the test results in a more flexible way, for
163 example, the diagnostic output may be quite long or complex or it may involve
164 something that you cannot predict in advance like a timestamp. In this case
165 you can get direct access to the test results:
166 .PP
167 .Vb 5
168 \& my ($premature, @results) = run_tests(
169 \& sub {
170 \& is_database_alive("dbname");
171 \& }
172 \& );
173 \&
174 \& like($result[0]\->{diag}, "/^Database ping took \e\ed+ seconds$"/, "diag");
175 .Ve
176 .PP
177 or
178 .PP
179 .Vb 8
180 \& check_test(
181 \& sub { is_mystyle_qr("this", "that", "not matching") },
182 \& {
183 \& ok => 0, # we expect the test to fail
184 \& name => "not matching",
185 \& diag => qr/Expected: \*(Aqthis\*(Aq\es+Got: \*(Aqthat\*(Aq/,
186 \& }
187 \& );
188 .Ve
189 .PP
190 We cannot predict how long the database ping will take so we use
191 Test::More\*(Aqs \fBlike()\fR test to check that the diagnostic string is of the right
192 form.
193 .SH "HOW TO USE (THE HARD WAY)"
194 .IX Header "HOW TO USE (THE HARD WAY)"
195 \&\fIThis is here for backwards compatibility only\fR
196 .PP
197 Make your module use the Test::Tester::Capture object instead of the
198 Test::Builder one. How to do this depends on your module but assuming that
199 your module holds the Test::Builder object in \f(CW$Test\fR and that all your test
200 routines access it through \f(CW$Test\fR then providing a function something like this
201 .PP
202 .Vb 4
203 \& sub set_builder
204 \& {
205 \& $Test = shift;
206 \& }
207 .Ve
208 .PP
209 should allow your test scripts to do
210 .PP
211 .Vb 1
212 \& Test::YourModule::set_builder(Test::Tester\->capture);
213 .Ve
214 .PP
215 and after that any tests inside your module will captured.
216 .SH "TEST RESULTS"
217 .IX Header "TEST RESULTS"
218 The result of each test is captured in a hash. These hashes are the same as
219 the hashes returned by Test::Builder\->details but with a couple of extra
220 fields.
221 .PP
222 These fields are documented in Test::Builder in the \fBdetails()\fR function
223 .IP ok 2
224 .IX Item "ok"
225 Did the test pass?
226 .IP actual_ok 2
227 .IX Item "actual_ok"
228 Did the test really pass? That is, did the pass come from
229 Test::Builder\->\fBok()\fR or did it pass because it was a TODO test?
230 .IP name 2
231 .IX Item "name"
232 The name supplied for the test.
233 .IP type 2
234 .IX Item "type"
235 What kind of test? Possibilities include, skip, todo etc. See
236 Test::Builder for more details.
237 .IP reason 2
238 .IX Item "reason"
239 The reason for the skip, todo etc. See Test::Builder for more details.
240 .PP
241 These fields are exclusive to Test::Tester.
242 .IP diag 2
243 .IX Item "diag"
244 Any diagnostics that were output for the test. This only includes
245 diagnostics output \fBafter\fR the test result is declared.
246 .Sp
247 Note that Test::Builder ensures that any diagnostics end in a \en and
248 it in earlier versions of Test::Tester it was essential that you have
249 the final \en in your expected diagnostics. From version 0.10 onward,
250 Test::Tester will add the \en if you forgot it. It will not add a \en if
251 you are expecting no diagnostics. See below for help tracking down
252 hard to find space and tab related problems.
253 .IP depth 2
254 .IX Item "depth"
255 This allows you to check that your test module is setting the correct value
256 for \f(CW$Test::Builder::Level\fR and thus giving the correct file and line number
257 when a test fails. It is calculated by looking at \fBcaller()\fR and
258 \&\f(CW$Test::Builder::Level\fR. It should count how many subroutines there are before
259 jumping into the function you are testing. So for example in
260 .Sp
261 .Vb 1
262 \& run_tests( sub { my_test_function("a", "b") } );
263 .Ve
264 .Sp
265 the depth should be 1 and in
266 .Sp
267 .Vb 1
268 \& sub deeper { my_test_function("a", "b") }
269 \&
270 \& run_tests(sub { deeper() });
271 .Ve
272 .Sp
273 depth should be 2, that is 1 for the sub {} and one for \fBdeeper()\fR. This
274 might seem a little complex but if your tests look like the simple
275 examples in this doc then you don\*(Aqt need to worry as the depth will
276 always be 1 and that\*(Aqs what Test::Tester expects by default.
277 .Sp
278 \&\fBNote\fR: if you do not specify a value for depth in \fBcheck_test()\fR then it
279 automatically compares it against 1, if you really want to skip the depth
280 test then pass in undef.
281 .Sp
282 \&\fBNote\fR: depth will not be correctly calculated for tests that run from a
283 signal handler or an END block or anywhere else that hides the call stack.
284 .PP
285 Some of Test::Tester\*(Aqs functions return arrays of these hashes, just
286 like Test::Builder\->details. That is, the hash for the first test will
287 be array element 1 (not 0). Element 0 will not be a hash it will be a
288 string which contains any diagnostic output that came before the first
289 test. This should usually be empty, if it\*(Aqs not, it means something
290 output diagnostics before any test results showed up.
291 .SH "SPACES AND TABS"
292 .IX Header "SPACES AND TABS"
293 Appearances can be deceptive, especially when it comes to emptiness. If you
294 are scratching your head trying to work out why Test::Tester is saying that
295 your diagnostics are wrong when they look perfectly right then the answer is
296 probably whitespace. From version 0.10 on, Test::Tester surrounds the
297 expected and got diag values with single quotes to make it easier to spot
298 trailing whitespace. So in this example
299 .PP
300 .Vb 4
301 \& # Got diag (5 bytes):
302 \& # \*(Aqabcd \*(Aq
303 \& # Expected diag (4 bytes):
304 \& # \*(Aqabcd\*(Aq
305 .Ve
306 .PP
307 it is quite clear that there is a space at the end of the first string.
308 Another way to solve this problem is to use colour and inverse video on an
309 ANSI terminal, see below COLOUR below if you want this.
310 .PP
311 Unfortunately this is sometimes not enough, neither colour nor quotes will
312 help you with problems involving tabs, other non\-printing characters and
313 certain kinds of problems inherent in Unicode. To deal with this, you can
314 switch Test::Tester into a mode whereby all "tricky" characters are shown as
315 \&\e{xx}. Tricky characters are those with ASCII code less than 33 or higher
316 than 126. This makes the output more difficult to read but much easier to
317 find subtle differences between strings. To turn on this mode either call
318 \&\f(CWshow_space()\fR in your test script or set the \f(CW\*(C`TESTTESTERSPACE\*(C'\fR environment
319 variable to be a true value. The example above would then look like
320 .PP
321 .Vb 4
322 \& # Got diag (5 bytes):
323 \& # abcd\ex{20}
324 \& # Expected diag (4 bytes):
325 \& # abcd
326 .Ve
327 .SH COLOUR
328 .IX Header "COLOUR"
329 If you prefer to use colour as a means of finding tricky whitespace
330 characters then you can set the \f(CW\*(C`TESTTESTCOLOUR\*(C'\fR environment variable to a
331 comma separated pair of colours, the first for the foreground, the second
332 for the background. For example "white,red" will print white text on a red
333 background. This requires the Term::ANSIColor module. You can specify any
334 colour that would be acceptable to the Term::ANSIColor::color function.
335 .PP
336 If you spell colour differently, that\*(Aqs no problem. The \f(CW\*(C`TESTTESTERCOLOR\*(C'\fR
337 variable also works (if both are set then the British spelling wins out).
338 .SH "EXPORTED FUNCTIONS"
339 .IX Header "EXPORTED FUNCTIONS"
340 \fI($premature, \fR\f(CI@results\fR\fI) = run_tests(\e&test_sub)\fR
341 .IX Subsection "($premature, @results) = run_tests(&test_sub)"
342 .PP
343 \&\e&test_sub is a reference to a subroutine.
344 .PP
345 run_tests runs the subroutine in \f(CW$test_sub\fR and captures the results of any
346 tests inside it. You can run more than 1 test inside this subroutine if you
347 like.
348 .PP
349 \&\f(CW$premature\fR is a string containing any diagnostic output from before
350 the first test.
351 .PP
352 \&\f(CW@results\fR is an array of test result hashes.
353 .PP
354 \fIcmp_result(\e%result, \e%expect, \fR\f(CI$name\fR\fI)\fR
355 .IX Subsection "cmp_result(%result, %expect, $name)"
356 .PP
357 \&\e%result is a ref to a test result hash.
358 .PP
359 \&\e%expect is a ref to a hash of expected values for the test result.
360 .PP
361 cmp_result compares the result with the expected values. If any differences
362 are found it outputs diagnostics. You may leave out any field from the
363 expected result and cmp_result will not do the comparison of that field.
364 .PP
365 \fIcmp_results(\e@results, \e@expects, \fR\f(CI$name\fR\fI)\fR
366 .IX Subsection "cmp_results(@results, @expects, $name)"
367 .PP
368 \&\e@results is a ref to an array of test results.
369 .PP
370 \&\e@expects is a ref to an array of hash refs.
371 .PP
372 cmp_results checks that the results match the expected results and if any
373 differences are found it outputs diagnostics. It first checks that the
374 number of elements in \e@results and \e@expects is the same. Then it goes
375 through each result checking it against the expected result as in
376 \&\fBcmp_result()\fR above.
377 .PP
378 \fI($premature, \fR\f(CI@results\fR\fI) = check_tests(\e&test_sub, \e@expects, \fR\f(CI$name\fR\fI)\fR
379 .IX Subsection "($premature, @results) = check_tests(&test_sub, @expects, $name)"
380 .PP
381 \&\e&test_sub is a reference to a subroutine.
382 .PP
383 \&\e@expect is a ref to an array of hash refs which are expected test results.
384 .PP
385 check_tests combines run_tests and cmp_tests into a single call. It also
386 checks if the tests died at any stage.
387 .PP
388 It returns the same values as run_tests, so you can further examine the test
389 results if you need to.
390 .PP
391 \fI($premature, \fR\f(CI@results\fR\fI) = check_test(\e&test_sub, \e%expect, \fR\f(CI$name\fR\fI)\fR
392 .IX Subsection "($premature, @results) = check_test(&test_sub, %expect, $name)"
393 .PP
394 \&\e&test_sub is a reference to a subroutine.
395 .PP
396 \&\e%expect is a ref to an hash of expected values for the test result.
397 .PP
398 check_test is a wrapper around check_tests. It combines run_tests and
399 cmp_tests into a single call, checking if the test died. It assumes
400 that only a single test is run inside \e&test_sub and include a test to
401 make sure this is true.
402 .PP
403 It returns the same values as run_tests, so you can further examine the test
404 results if you need to.
405 .PP
406 \fR\f(BIshow_space()\fR\fI\fR
407 .IX Subsection "show_space()"
408 .PP
409 Turn on the escaping of characters as described in the SPACES AND TABS
410 section.
411 .SH "HOW IT WORKS"
412 .IX Header "HOW IT WORKS"
413 Normally, a test module (let\*(Aqs call it Test:MyStyle) calls
414 Test::Builder\->new to get the Test::Builder object. Test::MyStyle calls
415 methods on this object to record information about test results. When
416 Test::Tester is loaded, it replaces Test::Builder\*(Aqs \fBnew()\fR method with one
417 which returns a Test::Tester::Delegate object. Most of the time this object
418 behaves as the real Test::Builder object. Any methods that are called are
419 delegated to the real Test::Builder object so everything works perfectly.
420 However once we go into test mode, the method calls are no longer passed to
421 the real Test::Builder object, instead they go to the Test::Tester::Capture
422 object. This object seems exactly like the real Test::Builder object,
423 except, instead of outputting test results and diagnostics, it just records
424 all the information for later analysis.
425 .SH CAVEATS
426 .IX Header "CAVEATS"
427 Support for calling Test::Builder\->note is minimal. It\*(Aqs implemented
428 as an empty stub, so modules that use it will not crash but the calls
429 are not recorded for testing purposes like the others. Patches
430 welcome.
431 .SH "SEE ALSO"
432 .IX Header "SEE ALSO"
433 Test::Builder the source of testing goodness. Test::Builder::Tester
434 for an alternative approach to the problem tackled by Test::Tester \-
435 captures the strings output by Test::Builder. This means you cannot get
436 separate access to the individual pieces of information and you must predict
437 \&\fBexactly\fR what your test will output.
438 .SH AUTHOR
439 .IX Header "AUTHOR"
440 This module is copyright 2005 Fergal Daly <[email protected]>, some parts
441 are based on other people\*(Aqs work.
442 .PP
443 Plan handling lifted from Test::More. written by Michael G Schwern
444 <[email protected]>.
445 .PP
446 Test::Tester::Capture is a cut down and hacked up version of Test::Builder.
447 Test::Builder was written by chromatic <[email protected]> and Michael G
448 Schwern <[email protected]>.
449 .SH LICENSE
450 .IX Header "LICENSE"
451 Under the same license as Perl itself
452 .PP
453 See <https://dev.perl.org/licenses/>