Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test::More.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::More 3pm"
61 .TH Test::More 3pm 2026-03-09 "perl v5.42.1" "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::More \- yet another framework for writing test scripts
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 5
71 \& use Test::More tests => 23;
72 \& # or
73 \& use Test::More skip_all => $reason;
74 \& # or
75 \& use Test::More; # see done_testing()
76 \&
77 \& require_ok( \*(AqSome::Module\*(Aq );
78 \&
79 \& # Various ways to say "ok"
80 \& ok($got eq $expected, $test_name);
81 \&
82 \& is ($got, $expected, $test_name);
83 \& isnt($got, $expected, $test_name);
84 \&
85 \& # Rather than print STDERR "# here\*(Aqs what went wrong\en"
86 \& diag("here\*(Aqs what went wrong");
87 \&
88 \& like ($got, qr/expected/, $test_name);
89 \& unlike($got, qr/expected/, $test_name);
90 \&
91 \& cmp_ok($got, \*(Aq==\*(Aq, $expected, $test_name);
92 \&
93 \& is_deeply($got_complex_structure, $expected_complex_structure, $test_name);
94 \&
95 \& SKIP: {
96 \& skip $why, $how_many unless $have_some_feature;
97 \&
98 \& ok( foo(), $test_name );
99 \& is( foo(42), 23, $test_name );
100 \& };
101 \&
102 \& TODO: {
103 \& local $TODO = $why;
104 \&
105 \& ok( foo(), $test_name );
106 \& is( foo(42), 23, $test_name );
107 \& };
108 \&
109 \& can_ok($module, @methods);
110 \& isa_ok($object, $class);
111 \&
112 \& pass($test_name);
113 \& fail($test_name);
114 \&
115 \& BAIL_OUT($why);
116 \&
117 \& # UNIMPLEMENTED!!!
118 \& my @status = Test::More::status;
119 .Ve
120 .SH DESCRIPTION
121 .IX Header "DESCRIPTION"
122 \&\fBSTOP!\fR If you\*(Aqre just getting started writing tests, have a look at
123 Test2::Suite first.
124 .PP
125 This is a drop in replacement for Test::Simple which you can switch to once you
126 get the hang of basic testing.
127 .PP
128 The purpose of this module is to provide a wide range of testing
129 utilities. Various ways to say "ok" with better diagnostics,
130 facilities to skip tests, test future features and compare complicated
131 data structures. While you can do almost anything with a simple
132 \&\f(CWok()\fR function, it doesn\*(Aqt provide good diagnostic output.
133 .SS "I love it when a plan comes together"
134 .IX Subsection "I love it when a plan comes together"
135 Before anything else, you need a testing plan. This basically declares
136 how many tests your script is going to run to protect against premature
137 failure.
138 .PP
139 The preferred way to do this is to declare a plan when you \f(CW\*(C`use Test::More\*(C'\fR.
140 .PP
141 .Vb 1
142 \& use Test::More tests => 23;
143 .Ve
144 .PP
145 There are cases when you will not know beforehand how many tests your
146 script is going to run. In this case, you can declare your tests at
147 the end.
148 .PP
149 .Vb 1
150 \& use Test::More;
151 \&
152 \& ... run your tests ...
153 \&
154 \& done_testing( $number_of_tests_run );
155 .Ve
156 .PP
157 \&\fBNOTE\fR \f(CWdone_testing()\fR should never be called in an \f(CW\*(C`END { ... }\*(C'\fR block.
158 .PP
159 Sometimes you really don\*(Aqt know how many tests were run, or it\*(Aqs too
160 difficult to calculate. In which case you can leave off
161 \&\f(CW$number_of_tests_run\fR.
162 .PP
163 In some cases, you\*(Aqll want to completely skip an entire testing script.
164 .PP
165 .Vb 1
166 \& use Test::More skip_all => $skip_reason;
167 .Ve
168 .PP
169 Your script will declare a skip with the reason why you skipped and
170 exit immediately with a zero (success). See Test::Harness for
171 details.
172 .PP
173 If you want to control what functions Test::More will export, you
174 have to use the \*(Aqimport\*(Aq option. For example, to import everything
175 but \*(Aqfail\*(Aq, you\*(Aqd do:
176 .PP
177 .Vb 1
178 \& use Test::More tests => 23, import => [\*(Aq!fail\*(Aq];
179 .Ve
180 .PP
181 Alternatively, you can use the \f(CWplan()\fR function. Useful for when you
182 have to calculate the number of tests.
183 .PP
184 .Vb 2
185 \& use Test::More;
186 \& plan tests => keys %Stuff * 3;
187 .Ve
188 .PP
189 or for deciding between running the tests at all:
190 .PP
191 .Vb 7
192 \& use Test::More;
193 \& if( $^O eq \*(AqMacOS\*(Aq ) {
194 \& plan skip_all => \*(AqTest irrelevant on MacOS\*(Aq;
195 \& }
196 \& else {
197 \& plan tests => 42;
198 \& }
199 .Ve
200 .IP \fBdone_testing\fR 4
201 .IX Item "done_testing"
202 .Vb 2
203 \& done_testing();
204 \& done_testing($number_of_tests);
205 .Ve
206 .Sp
207 If you don\*(Aqt know how many tests you\*(Aqre going to run, you can issue
208 the plan when you\*(Aqre done running tests.
209 .Sp
210 \&\f(CW$number_of_tests\fR is the same as \f(CWplan()\fR, it\*(Aqs the number of tests you
211 expected to run. You can omit this, in which case the number of tests
212 you ran doesn\*(Aqt matter, just the fact that your tests ran to
213 conclusion.
214 .Sp
215 This is safer than and replaces the "no_plan" plan.
216 .Sp
217 \&\fBNote:\fR You must never put \f(CWdone_testing()\fR inside an \f(CW\*(C`END { ... }\*(C'\fR block.
218 The plan is there to ensure your test does not exit before testing has
219 completed. If you use an END block you completely bypass this protection.
220 .SS "Test names"
221 .IX Subsection "Test names"
222 By convention, each test is assigned a number in order. This is
223 largely done automatically for you. However, it\*(Aqs often very useful to
224 assign a name to each test. Which would you rather see:
225 .PP
226 .Vb 3
227 \& ok 4
228 \& not ok 5
229 \& ok 6
230 .Ve
231 .PP
232 or
233 .PP
234 .Vb 3
235 \& ok 4 \- basic multi\-variable
236 \& not ok 5 \- simple exponential
237 \& ok 6 \- force == mass * acceleration
238 .Ve
239 .PP
240 The later gives you some idea of what failed. It also makes it easier
241 to find the test in your script, simply search for "simple
242 exponential".
243 .PP
244 All test functions take a name argument. It\*(Aqs optional, but highly
245 suggested that you use it.
246 .SS "I\*(Aqm ok, you\*(Aqre not ok."
247 .IX Subsection "I'm ok, you're not ok."
248 The basic purpose of this module is to print out either "ok #" or "not
249 ok #" depending on if a given test succeeded or failed. Everything
250 else is just gravy.
251 .PP
252 All of the following print "ok" or "not ok" depending on if the test
253 succeeded or failed. They all also return true or false,
254 respectively.
255 .IP \fBok\fR 4
256 .IX Item "ok"
257 .Vb 1
258 \& ok($got eq $expected, $test_name);
259 .Ve
260 .Sp
261 This simply evaluates any expression (\f(CW\*(C`$got eq $expected\*(C'\fR is just a
262 simple example) and uses that to determine if the test succeeded or
263 failed. A true expression passes, a false one fails. Very simple.
264 .Sp
265 For example:
266 .Sp
267 .Vb 4
268 \& ok( $exp{9} == 81, \*(Aqsimple exponential\*(Aq );
269 \& ok( Film\->can(\*(Aqdb_Main\*(Aq), \*(Aqset_db()\*(Aq );
270 \& ok( $p\->tests == 4, \*(Aqsaw tests\*(Aq );
271 \& ok( !grep(!defined $_, @items), \*(Aqall items defined\*(Aq );
272 .Ve
273 .Sp
274 (Mnemonic: "This is ok.")
275 .Sp
276 \&\f(CW$test_name\fR is a very short description of the test that will be printed
277 out. It makes it very easy to find a test in your script when it fails
278 and gives others an idea of your intentions. \f(CW$test_name\fR is optional,
279 but we \fBvery\fR strongly encourage its use.
280 .Sp
281 Should an \f(CWok()\fR fail, it will produce some diagnostics:
282 .Sp
283 .Vb 3
284 \& not ok 18 \- sufficient mucus
285 \& # Failed test \*(Aqsufficient mucus\*(Aq
286 \& # in foo.t at line 42.
287 .Ve
288 .Sp
289 This is the same as Test::Simple\*(Aqs \f(CWok()\fR routine.
290 .IP \fBis\fR 4
291 .IX Item "is"
292 .PD 0
293 .IP \fBisnt\fR 4
294 .IX Item "isnt"
295 .PD
296 .Vb 2
297 \& is ( $got, $expected, $test_name );
298 \& isnt( $got, $expected, $test_name );
299 .Ve
300 .Sp
301 Similar to \f(CWok()\fR, \f(CWis()\fR and \f(CWisnt()\fR compare their two arguments
302 with \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`ne\*(C'\fR respectively and use the result of that to
303 determine if the test succeeded or failed. So these:
304 .Sp
305 .Vb 2
306 \& # Is the ultimate answer 42?
307 \& is( ultimate_answer(), 42, "Meaning of Life" );
308 \&
309 \& # $foo isn\*(Aqt empty
310 \& isnt( $foo, \*(Aq\*(Aq, "Got some foo" );
311 .Ve
312 .Sp
313 are similar to these:
314 .Sp
315 .Vb 2
316 \& ok( ultimate_answer() eq 42, "Meaning of Life" );
317 \& ok( $foo ne \*(Aq\*(Aq, "Got some foo" );
318 .Ve
319 .Sp
320 \&\f(CW\*(C`undef\*(C'\fR will only ever match \f(CW\*(C`undef\*(C'\fR. So you can test a value
321 against \f(CW\*(C`undef\*(C'\fR like this:
322 .Sp
323 .Vb 1
324 \& is($not_defined, undef, "undefined as expected");
325 .Ve
326 .Sp
327 (Mnemonic: "This is that." "This isn\*(Aqt that.")
328 .Sp
329 So why use these? They produce better diagnostics on failure. \f(CWok()\fR
330 cannot know what you are testing for (beyond the name), but \f(CWis()\fR and
331 \&\f(CWisnt()\fR know what the test was and why it failed. For example this
332 test:
333 .Sp
334 .Vb 2
335 \& my $foo = \*(Aqwaffle\*(Aq; my $bar = \*(Aqyarblokos\*(Aq;
336 \& is( $foo, $bar, \*(AqIs foo the same as bar?\*(Aq );
337 .Ve
338 .Sp
339 Will produce something like this:
340 .Sp
341 .Vb 5
342 \& not ok 17 \- Is foo the same as bar?
343 \& # Failed test \*(AqIs foo the same as bar?\*(Aq
344 \& # in foo.t at line 139.
345 \& # got: \*(Aqwaffle\*(Aq
346 \& # expected: \*(Aqyarblokos\*(Aq
347 .Ve
348 .Sp
349 So you can figure out what went wrong without rerunning the test.
350 .Sp
351 You are encouraged to use \f(CWis()\fR and \f(CWisnt()\fR over \f(CWok()\fR where possible,
352 however do not be tempted to use them to find out if something is
353 true or false!
354 .Sp
355 .Vb 2
356 \& # XXX BAD!
357 \& is( exists $brooklyn{tree}, 1, \*(AqA tree grows in Brooklyn\*(Aq );
358 .Ve
359 .Sp
360 This does not check if \f(CW\*(C`exists $brooklyn{tree}\*(C'\fR is true, it checks if
361 it returns 1. Very different. Similar caveats exist for false and 0.
362 In these cases, use \f(CWok()\fR.
363 .Sp
364 .Vb 1
365 \& ok( exists $brooklyn{tree}, \*(AqA tree grows in Brooklyn\*(Aq );
366 .Ve
367 .Sp
368 A simple call to \f(CWisnt()\fR usually does not provide a strong test but there
369 are cases when you cannot say much more about a value than that it is
370 different from some other value:
371 .Sp
372 .Vb 1
373 \& new_ok $obj, "Foo";
374 \&
375 \& my $clone = $obj\->clone;
376 \& isa_ok $obj, "Foo", "Foo\->clone";
377 \&
378 \& isnt $obj, $clone, "clone() produces a different object";
379 .Ve
380 .Sp
381 Historically we supported an \f(CW\*(C`isn\*(Aqt()\*(C'\fR function as an alias of
382 \&\f(CWisnt()\fR, however in Perl 5.37.9 support for the use of apostrophe as
383 a package separator was deprecated and by Perl 5.42.0 support for it
384 will have been removed completely. Accordingly use of \f(CW\*(C`isn\*(Aqt()\*(C'\fR is also
385 deprecated, and will produce warnings when used unless \*(Aqdeprecated\*(Aq
386 warnings are specifically disabled in the scope where it is used. You
387 are strongly advised to migrate to using \f(CWisnt()\fR instead.
388 .IP \fBlike\fR 4
389 .IX Item "like"
390 .Vb 1
391 \& like( $got, qr/expected/, $test_name );
392 .Ve
393 .Sp
394 Similar to \f(CWok()\fR, \f(CWlike()\fR matches \f(CW$got\fR against the regex \f(CW\*(C`qr/expected/\*(C'\fR.
395 .Sp
396 So this:
397 .Sp
398 .Vb 1
399 \& like($got, qr/expected/, \*(Aqthis is like that\*(Aq);
400 .Ve
401 .Sp
402 is similar to:
403 .Sp
404 .Vb 1
405 \& ok( $got =~ m/expected/, \*(Aqthis is like that\*(Aq);
406 .Ve
407 .Sp
408 (Mnemonic "This is like that".)
409 .Sp
410 The second argument is a regular expression. It may be given as a
411 regex reference (i.e. \f(CW\*(C`qr//\*(C'\fR) or (for better compatibility with older
412 perls) as a string that looks like a regex (alternative delimiters are
413 currently not supported):
414 .Sp
415 .Vb 1
416 \& like( $got, \*(Aq/expected/\*(Aq, \*(Aqthis is like that\*(Aq );
417 .Ve
418 .Sp
419 Regex options may be placed on the end (\f(CW\*(Aq/expected/i\*(Aq\fR).
420 .Sp
421 Its advantages over \f(CWok()\fR are similar to that of \f(CWis()\fR and \f(CWisnt()\fR. Better
422 diagnostics on failure.
423 .IP \fBunlike\fR 4
424 .IX Item "unlike"
425 .Vb 1
426 \& unlike( $got, qr/expected/, $test_name );
427 .Ve
428 .Sp
429 Works exactly as \f(CWlike()\fR, only it checks if \f(CW$got\fR \fBdoes not\fR match the
430 given pattern.
431 .IP \fBcmp_ok\fR 4
432 .IX Item "cmp_ok"
433 .Vb 1
434 \& cmp_ok( $got, $op, $expected, $test_name );
435 .Ve
436 .Sp
437 Halfway between \f(CWok()\fR and \f(CWis()\fR lies \f(CWcmp_ok()\fR. This allows you
438 to compare two arguments using any binary perl operator. The test
439 passes if the comparison is true and fails otherwise.
440 .Sp
441 .Vb 2
442 \& # ok( $got eq $expected );
443 \& cmp_ok( $got, \*(Aqeq\*(Aq, $expected, \*(Aqthis eq that\*(Aq );
444 \&
445 \& # ok( $got == $expected );
446 \& cmp_ok( $got, \*(Aq==\*(Aq, $expected, \*(Aqthis == that\*(Aq );
447 \&
448 \& # ok( $got && $expected );
449 \& cmp_ok( $got, \*(Aq&&\*(Aq, $expected, \*(Aqthis && that\*(Aq );
450 \& ...etc...
451 .Ve
452 .Sp
453 Its advantage over \f(CWok()\fR is when the test fails you\*(Aqll know what \f(CW$got\fR
454 and \f(CW$expected\fR were:
455 .Sp
456 .Vb 5
457 \& not ok 1
458 \& # Failed test in foo.t at line 12.
459 \& # \*(Aq23\*(Aq
460 \& # &&
461 \& # undef
462 .Ve
463 .Sp
464 It\*(Aqs also useful in those cases where you are comparing numbers and
465 \&\f(CWis()\fR\*(Aqs use of \f(CW\*(C`eq\*(C'\fR will interfere:
466 .Sp
467 .Vb 1
468 \& cmp_ok( $big_hairy_number, \*(Aq==\*(Aq, $another_big_hairy_number );
469 .Ve
470 .Sp
471 It\*(Aqs especially useful when comparing greater\-than or smaller\-than
472 relation between values:
473 .Sp
474 .Vb 1
475 \& cmp_ok( $some_value, \*(Aq<=\*(Aq, $upper_limit );
476 .Ve
477 .IP \fBcan_ok\fR 4
478 .IX Item "can_ok"
479 .Vb 2
480 \& can_ok($module, @methods);
481 \& can_ok($object, @methods);
482 .Ve
483 .Sp
484 Checks to make sure the \f(CW$module\fR or \f(CW$object\fR can do these \f(CW@methods\fR
485 (works with functions, too).
486 .Sp
487 .Vb 1
488 \& can_ok(\*(AqFoo\*(Aq, qw(this that whatever));
489 .Ve
490 .Sp
491 is almost exactly like saying:
492 .Sp
493 .Vb 4
494 \& ok( Foo\->can(\*(Aqthis\*(Aq) &&
495 \& Foo\->can(\*(Aqthat\*(Aq) &&
496 \& Foo\->can(\*(Aqwhatever\*(Aq)
497 \& );
498 .Ve
499 .Sp
500 only without all the typing and with a better interface. Handy for
501 quickly testing an interface.
502 .Sp
503 No matter how many \f(CW@methods\fR you check, a single \f(CWcan_ok()\fR call counts
504 as one test. If you desire otherwise, use:
505 .Sp
506 .Vb 3
507 \& foreach my $meth (@methods) {
508 \& can_ok(\*(AqFoo\*(Aq, $meth);
509 \& }
510 .Ve
511 .IP \fBisa_ok\fR 4
512 .IX Item "isa_ok"
513 .Vb 3
514 \& isa_ok($object, $class, $object_name);
515 \& isa_ok($subclass, $class, $object_name);
516 \& isa_ok($ref, $type, $ref_name);
517 .Ve
518 .Sp
519 Checks to see if the given \f(CW\*(C`$object\->isa($class)\*(C'\fR. Also checks to make
520 sure the object was defined in the first place. Handy for this sort
521 of thing:
522 .Sp
523 .Vb 2
524 \& my $obj = Some::Module\->new;
525 \& isa_ok( $obj, \*(AqSome::Module\*(Aq );
526 .Ve
527 .Sp
528 where you\*(Aqd otherwise have to write
529 .Sp
530 .Vb 2
531 \& my $obj = Some::Module\->new;
532 \& ok( defined $obj && $obj\->isa(\*(AqSome::Module\*(Aq) );
533 .Ve
534 .Sp
535 to safeguard against your test script blowing up.
536 .Sp
537 You can also test a class, to make sure that it has the right ancestor:
538 .Sp
539 .Vb 1
540 \& isa_ok( \*(AqVole\*(Aq, \*(AqRodent\*(Aq );
541 .Ve
542 .Sp
543 It works on references, too:
544 .Sp
545 .Vb 1
546 \& isa_ok( $array_ref, \*(AqARRAY\*(Aq );
547 .Ve
548 .Sp
549 The diagnostics of this test normally just refer to \*(Aqthe object\*(Aq. If
550 you\*(Aqd like them to be more specific, you can supply an \f(CW$object_name\fR
551 (for example \*(AqTest customer\*(Aq).
552 .IP \fBnew_ok\fR 4
553 .IX Item "new_ok"
554 .Vb 3
555 \& my $obj = new_ok( $class );
556 \& my $obj = new_ok( $class => \e@args );
557 \& my $obj = new_ok( $class => \e@args, $object_name );
558 .Ve
559 .Sp
560 A convenience function which combines creating an object and calling
561 \&\f(CWisa_ok()\fR on that object.
562 .Sp
563 It is basically equivalent to:
564 .Sp
565 .Vb 2
566 \& my $obj = $class\->new(@args);
567 \& isa_ok $obj, $class, $object_name;
568 .Ve
569 .Sp
570 If \f(CW@args\fR is not given, an empty list will be used.
571 .Sp
572 This function only works on \f(CWnew()\fR and it assumes \f(CWnew()\fR will return
573 just a single object which isa \f(CW$class\fR.
574 .IP \fBsubtest\fR 4
575 .IX Item "subtest"
576 .Vb 1
577 \& subtest $name => \e&code, @args;
578 .Ve
579 .Sp
580 \&\f(CWsubtest()\fR runs the &code as its own little test with its own plan and
581 its own result. The main test counts this as a single test using the
582 result of the whole subtest to determine if its ok or not ok.
583 .Sp
584 For example...
585 .Sp
586 .Vb 1
587 \& use Test::More tests => 3;
588 \&
589 \& pass("First test");
590 \&
591 \& subtest \*(AqAn example subtest\*(Aq => sub {
592 \& plan tests => 2;
593 \&
594 \& pass("This is a subtest");
595 \& pass("So is this");
596 \& };
597 \&
598 \& pass("Third test");
599 .Ve
600 .Sp
601 This would produce.
602 .Sp
603 .Vb 8
604 \& 1..3
605 \& ok 1 \- First test
606 \& # Subtest: An example subtest
607 \& 1..2
608 \& ok 1 \- This is a subtest
609 \& ok 2 \- So is this
610 \& ok 2 \- An example subtest
611 \& ok 3 \- Third test
612 .Ve
613 .Sp
614 A subtest may call \f(CW\*(C`skip_all\*(C'\fR. No tests will be run, but the subtest is
615 considered a skip.
616 .Sp
617 .Vb 4
618 \& subtest \*(Aqskippy\*(Aq => sub {
619 \& plan skip_all => \*(Aqcuz I said so\*(Aq;
620 \& pass(\*(Aqthis test will never be run\*(Aq);
621 \& };
622 .Ve
623 .Sp
624 Returns true if the subtest passed, false otherwise.
625 .Sp
626 Due to how subtests work, you may omit a plan if you desire. This adds an
627 implicit \f(CWdone_testing()\fR to the end of your subtest. The following two
628 subtests are equivalent:
629 .Sp
630 .Vb 5
631 \& subtest \*(Aqsubtest with implicit done_testing()\*(Aq, sub {
632 \& ok 1, \*(Aqsubtests with an implicit done testing should work\*(Aq;
633 \& ok 1, \*(Aq... and support more than one test\*(Aq;
634 \& ok 1, \*(Aq... no matter how many tests are run\*(Aq;
635 \& };
636 \&
637 \& subtest \*(Aqsubtest with explicit done_testing()\*(Aq, sub {
638 \& ok 1, \*(Aqsubtests with an explicit done testing should work\*(Aq;
639 \& ok 1, \*(Aq... and support more than one test\*(Aq;
640 \& ok 1, \*(Aq... no matter how many tests are run\*(Aq;
641 \& done_testing();
642 \& };
643 .Ve
644 .Sp
645 Extra arguments given to \f(CW\*(C`subtest\*(C'\fR are passed to the callback. For example:
646 .Sp
647 .Vb 4
648 \& sub my_subtest {
649 \& my $range = shift;
650 \& ...
651 \& }
652 \&
653 \& for my $range (1, 10, 100, 1000) {
654 \& subtest "testing range $range", \e&my_subtest, $range;
655 \& }
656 .Ve
657 .IP \fBpass\fR 4
658 .IX Item "pass"
659 .PD 0
660 .IP \fBfail\fR 4
661 .IX Item "fail"
662 .PD
663 .Vb 2
664 \& pass($test_name);
665 \& fail($test_name);
666 .Ve
667 .Sp
668 Sometimes you just want to say that the tests have passed. Usually
669 the case is you\*(Aqve got some complicated condition that is difficult to
670 wedge into an \f(CWok()\fR. In this case, you can simply use \f(CWpass()\fR (to
671 declare the test ok) or fail (for not ok). They are synonyms for
672 \&\f(CWok(1)\fR and \f(CWok(0)\fR.
673 .Sp
674 Use these very, very, very sparingly.
675 .SS "Module tests"
676 .IX Subsection "Module tests"
677 Sometimes you want to test if a module, or a list of modules, can
678 successfully load. For example, you\*(Aqll often want a first test which
679 simply loads all the modules in the distribution to make sure they
680 work before going on to do more complicated testing.
681 .PP
682 For such purposes we have \f(CW\*(C`use_ok\*(C'\fR and \f(CW\*(C`require_ok\*(C'\fR.
683 .IP \fBrequire_ok\fR 4
684 .IX Item "require_ok"
685 .Vb 2
686 \& require_ok($module);
687 \& require_ok($file);
688 .Ve
689 .Sp
690 Tries to \f(CW\*(C`require\*(C'\fR the given \f(CW$module\fR or \f(CW$file\fR. If it loads
691 successfully, the test will pass. Otherwise it fails and displays the
692 load error.
693 .Sp
694 \&\f(CW\*(C`require_ok\*(C'\fR will guess whether the input is a module name or a
695 filename.
696 .Sp
697 No exception will be thrown if the load fails.
698 .Sp
699 .Vb 2
700 \& # require Some::Module
701 \& require_ok "Some::Module";
702 \&
703 \& # require "Some/File.pl";
704 \& require_ok "Some/File.pl";
705 \&
706 \& # stop testing if any of your modules will not load
707 \& for my $module (@module) {
708 \& require_ok $module or BAIL_OUT "Can\*(Aqt load $module";
709 \& }
710 .Ve
711 .IP \fBuse_ok\fR 4
712 .IX Item "use_ok"
713 .Vb 2
714 \& BEGIN { use_ok($module); }
715 \& BEGIN { use_ok($module, @imports); }
716 .Ve
717 .Sp
718 Like \f(CW\*(C`require_ok\*(C'\fR, but it will \f(CW\*(C`use\*(C'\fR the \f(CW$module\fR in question and
719 only loads modules, not files.
720 .Sp
721 If you just want to test a module can be loaded, use \f(CW\*(C`require_ok\*(C'\fR.
722 .Sp
723 If you just want to load a module in a test, we recommend simply using
724 \&\f(CW\*(C`use\*(C'\fR directly. It will cause the test to stop.
725 .Sp
726 It\*(Aqs recommended that you run \f(CWuse_ok()\fR inside a BEGIN block so its
727 functions are exported at compile\-time and prototypes are properly
728 honored.
729 .Sp
730 If \f(CW@imports\fR are given, they are passed through to the use. So this:
731 .Sp
732 .Vb 1
733 \& BEGIN { use_ok(\*(AqSome::Module\*(Aq, qw(foo bar)) }
734 .Ve
735 .Sp
736 is like doing this:
737 .Sp
738 .Vb 1
739 \& use Some::Module qw(foo bar);
740 .Ve
741 .Sp
742 Version numbers can be checked like so:
743 .Sp
744 .Vb 2
745 \& # Just like "use Some::Module 1.02"
746 \& BEGIN { use_ok(\*(AqSome::Module\*(Aq, 1.02) }
747 .Ve
748 .Sp
749 Don\*(Aqt try to do this:
750 .Sp
751 .Vb 2
752 \& BEGIN {
753 \& use_ok(\*(AqSome::Module\*(Aq);
754 \&
755 \& ...some code that depends on the use...
756 \& ...happening at compile time...
757 \& }
758 .Ve
759 .Sp
760 because the notion of "compile\-time" is relative. Instead, you want:
761 .Sp
762 .Vb 2
763 \& BEGIN { use_ok(\*(AqSome::Module\*(Aq) }
764 \& BEGIN { ...some code that depends on the use... }
765 .Ve
766 .Sp
767 If you want the equivalent of \f(CW\*(C`use Foo ()\*(C'\fR, use a module but not
768 import anything, use \f(CW\*(C`require_ok\*(C'\fR.
769 .Sp
770 .Vb 1
771 \& BEGIN { require_ok "Foo" }
772 .Ve
773 .SS "Complex data structures"
774 .IX Subsection "Complex data structures"
775 Not everything is a simple eq check or regex. There are times you
776 need to see if two data structures are equivalent. For these
777 instances Test::More provides a handful of useful functions.
778 .PP
779 \&\fBNOTE\fR I\*(Aqm not quite sure what will happen with filehandles.
780 .IP \fBis_deeply\fR 4
781 .IX Item "is_deeply"
782 .Vb 1
783 \& is_deeply( $got, $expected, $test_name );
784 .Ve
785 .Sp
786 Similar to \f(CWis()\fR, except that if \f(CW$got\fR and \f(CW$expected\fR are references, it
787 does a deep comparison walking each data structure to see if they are
788 equivalent. If the two structures are different, it will display the
789 place where they start differing.
790 .Sp
791 \&\f(CWis_deeply()\fR compares the dereferenced values of references, the
792 references themselves (except for their type) are ignored. This means
793 aspects such as blessing and ties are not considered "different".
794 .Sp
795 \&\f(CWis_deeply()\fR currently has very limited handling of function reference
796 and globs. It merely checks if they have the same referent. This may
797 improve in the future.
798 .Sp
799 Test::Differences and Test::Deep provide more in\-depth functionality
800 along these lines.
801 .Sp
802 \&\fBNOTE\fR \fBis_deeply()\fR has limitations when it comes to comparing strings and
803 refs:
804 .Sp
805 .Vb 4
806 \& my $path = path(\*(Aq.\*(Aq);
807 \& my $hash = {};
808 \& is_deeply( $path, "$path" ); # ok
809 \& is_deeply( $hash, "$hash" ); # fail
810 .Ve
811 .Sp
812 This happens because is_deeply will unoverload all arguments unconditionally.
813 It is probably best not to use is_deeply with overloading. For legacy reasons
814 this is not likely to ever be fixed. If you would like a much better tool for
815 this you should see Test2::Suite Specifically Test2::Tools::Compare has
816 an \f(CWis()\fR function that works like \f(CW\*(C`is_deeply\*(C'\fR with many improvements.
817 .SS Diagnostics
818 .IX Subsection "Diagnostics"
819 If you pick the right test function, you\*(Aqll usually get a good idea of
820 what went wrong when it failed. But sometimes it doesn\*(Aqt work out
821 that way. So here we have ways for you to write your own diagnostic
822 messages which are safer than just \f(CW\*(C`print STDERR\*(C'\fR.
823 .IP \fBdiag\fR 4
824 .IX Item "diag"
825 .Vb 1
826 \& diag(@diagnostic_message);
827 .Ve
828 .Sp
829 Prints a diagnostic message which is guaranteed not to interfere with
830 test output. Like \f(CW\*(C`print\*(C'\fR \f(CW@diagnostic_message\fR is simply concatenated
831 together.
832 .Sp
833 Returns false, so as to preserve failure.
834 .Sp
835 Handy for this sort of thing:
836 .Sp
837 .Vb 2
838 \& ok( grep(/foo/, @users), "There\*(Aqs a foo user" ) or
839 \& diag("Since there\*(Aqs no foo, check that /etc/bar is set up right");
840 .Ve
841 .Sp
842 which would produce:
843 .Sp
844 .Vb 4
845 \& not ok 42 \- There\*(Aqs a foo user
846 \& # Failed test \*(AqThere\*(Aqs a foo user\*(Aq
847 \& # in foo.t at line 52.
848 \& # Since there\*(Aqs no foo, check that /etc/bar is set up right.
849 .Ve
850 .Sp
851 You might remember \f(CW\*(C`ok() or diag()\*(C'\fR with the mnemonic \f(CWopen() or
852 die()\fR.
853 .Sp
854 \&\fBNOTE\fR The exact formatting of the diagnostic output is still
855 changing, but it is guaranteed that whatever you throw at it won\*(Aqt
856 interfere with the test.
857 .IP \fBnote\fR 4
858 .IX Item "note"
859 .Vb 1
860 \& note(@diagnostic_message);
861 .Ve
862 .Sp
863 Like \f(CWdiag()\fR, except the message will not be seen when the test is run
864 in a harness. It will only be visible in the verbose TAP stream.
865 .Sp
866 Handy for putting in notes which might be useful for debugging, but
867 don\*(Aqt indicate a problem.
868 .Sp
869 .Vb 1
870 \& note("Tempfile is $tempfile");
871 .Ve
872 .IP \fBexplain\fR 4
873 .IX Item "explain"
874 .Vb 1
875 \& my @dump = explain @diagnostic_message;
876 .Ve
877 .Sp
878 Will dump the contents of any references in a human readable format.
879 Usually you want to pass this into \f(CW\*(C`note\*(C'\fR or \f(CW\*(C`diag\*(C'\fR.
880 .Sp
881 Handy for things like...
882 .Sp
883 .Vb 1
884 \& is_deeply($have, $want) || diag explain $have;
885 .Ve
886 .Sp
887 or
888 .Sp
889 .Vb 2
890 \& note explain \e%args;
891 \& Some::Class\->method(%args);
892 .Ve
893 .SS "Conditional tests"
894 .IX Subsection "Conditional tests"
895 Sometimes running a test under certain conditions will cause the
896 test script to die. A certain function or method isn\*(Aqt implemented
897 (such as \f(CWfork()\fR on MacOS), some resource isn\*(Aqt available (like a
898 net connection) or a module isn\*(Aqt available. In these cases it\*(Aqs
899 necessary to skip tests, or declare that they are supposed to fail
900 but will work in the future (a todo test).
901 .PP
902 For more details on the mechanics of skip and todo tests see
903 Test::Harness.
904 .PP
905 The way Test::More handles this is with a named block. Basically, a
906 block of tests which can be skipped over or made todo. It\*(Aqs best if I
907 just show you...
908 .IP "\fBSKIP: BLOCK\fR" 4
909 .IX Item "SKIP: BLOCK"
910 .Vb 2
911 \& SKIP: {
912 \& skip $why, $how_many if $condition;
913 \&
914 \& ...normal testing code goes here...
915 \& }
916 .Ve
917 .Sp
918 This declares a block of tests that might be skipped, \f(CW$how_many\fR tests
919 there are, \f(CW$why\fR and under what \f(CW$condition\fR to skip them. An example is
920 the easiest way to illustrate:
921 .Sp
922 .Vb 2
923 \& SKIP: {
924 \& eval { require HTML::Lint };
925 \&
926 \& skip "HTML::Lint not installed", 2 if $@;
927 \&
928 \& my $lint = new HTML::Lint;
929 \& isa_ok( $lint, "HTML::Lint" );
930 \&
931 \& $lint\->parse( $html );
932 \& is( $lint\->errors, 0, "No errors found in HTML" );
933 \& }
934 .Ve
935 .Sp
936 If the user does not have HTML::Lint installed, the whole block of
937 code \fIwon\*(Aqt be run at all\fR. Test::More will output special ok\*(Aqs
938 which Test::Harness interprets as skipped, but passing, tests.
939 .Sp
940 It\*(Aqs important that \f(CW$how_many\fR accurately reflects the number of tests
941 in the SKIP block so the # of tests run will match up with your plan.
942 If your plan is \f(CW\*(C`no_plan\*(C'\fR \f(CW$how_many\fR is optional and will default to 1.
943 .Sp
944 It\*(Aqs perfectly safe to nest SKIP blocks. Each SKIP block must have
945 the label \f(CW\*(C`SKIP\*(C'\fR, or Test::More can\*(Aqt work its magic.
946 .Sp
947 You don\*(Aqt skip tests which are failing because there\*(Aqs a bug in your
948 program, or for which you don\*(Aqt yet have code written. For that you
949 use TODO. Read on.
950 .IP "\fBTODO: BLOCK\fR" 4
951 .IX Item "TODO: BLOCK"
952 .Vb 2
953 \& TODO: {
954 \& local $TODO = $why if $condition;
955 \&
956 \& ...normal testing code goes here...
957 \& }
958 .Ve
959 .Sp
960 Declares a block of tests you expect to fail and \f(CW$why\fR. Perhaps it\*(Aqs
961 because you haven\*(Aqt fixed a bug or haven\*(Aqt finished a new feature:
962 .Sp
963 .Vb 2
964 \& TODO: {
965 \& local $TODO = "URI::Geller not finished";
966 \&
967 \& my $card = "Eight of clubs";
968 \& is( URI::Geller\->your_card, $card, \*(AqIs THIS your card?\*(Aq );
969 \&
970 \& my $spoon;
971 \& URI::Geller\->bend_spoon;
972 \& is( $spoon, \*(Aqbent\*(Aq, "Spoon bending, that\*(Aqs original" );
973 \& }
974 .Ve
975 .Sp
976 With a todo block, the tests inside are expected to fail. Test::More
977 will run the tests normally, but print out special flags indicating
978 they are "todo". Test::Harness will interpret failures as being ok.
979 Should anything succeed, it will report it as an unexpected success.
980 You then know the thing you had todo is done and can remove the
981 TODO flag.
982 .Sp
983 The nice part about todo tests, as opposed to simply commenting out a
984 block of tests, is that it is like having a programmatic todo list. You know
985 how much work is left to be done, you\*(Aqre aware of what bugs there are,
986 and you\*(Aqll know immediately when they\*(Aqre fixed.
987 .Sp
988 Once a todo test starts succeeding, simply move it outside the block.
989 When the block is empty, delete it.
990 .Sp
991 Note that, if you leave \f(CW$TODO\fR unset or undef, Test::More reports failures
992 as normal. This can be useful to mark the tests as expected to fail only
993 in certain conditions, e.g.:
994 .Sp
995 .Vb 2
996 \& TODO: {
997 \& local $TODO = "$^O doesn\*(Aqt work yet. :(" if !_os_is_supported($^O);
998 \&
999 \& ...
1000 \& }
1001 .Ve
1002 .IP \fBtodo_skip\fR 4
1003 .IX Item "todo_skip"
1004 .Vb 2
1005 \& TODO: {
1006 \& todo_skip $why, $how_many if $condition;
1007 \&
1008 \& ...normal testing code...
1009 \& }
1010 .Ve
1011 .Sp
1012 With todo tests, it\*(Aqs best to have the tests actually run. That way
1013 you\*(Aqll know when they start passing. Sometimes this isn\*(Aqt possible.
1014 Often a failing test will cause the whole program to die or hang, even
1015 inside an \f(CW\*(C`eval BLOCK\*(C'\fR with and using \f(CW\*(C`alarm\*(C'\fR. In these extreme
1016 cases you have no choice but to skip over the broken tests entirely.
1017 .Sp
1018 The syntax and behavior is similar to a \f(CW\*(C`SKIP: BLOCK\*(C'\fR except the
1019 tests will be marked as failing but todo. Test::Harness will
1020 interpret them as passing.
1021 .IP "When do I use SKIP vs. TODO?" 4
1022 .IX Item "When do I use SKIP vs. TODO?"
1023 \&\fBIf it\*(Aqs something the user might not be able to do\fR, use SKIP.
1024 This includes optional modules that aren\*(Aqt installed, running under
1025 an OS that doesn\*(Aqt have some feature (like \f(CWfork()\fR or symlinks), or maybe
1026 you need an Internet connection and one isn\*(Aqt available.
1027 .Sp
1028 \&\fBIf it\*(Aqs something the programmer hasn\*(Aqt done yet\fR, use TODO. This
1029 is for any code you haven\*(Aqt written yet, or bugs you have yet to fix,
1030 but want to put tests in your testing script (always a good idea).
1031 .SS "Test control"
1032 .IX Subsection "Test control"
1033 .IP \fBBAIL_OUT\fR 4
1034 .IX Item "BAIL_OUT"
1035 .Vb 1
1036 \& BAIL_OUT($reason);
1037 .Ve
1038 .Sp
1039 Indicates to the harness that things are going so badly all testing
1040 should terminate. This includes the running of any additional test scripts.
1041 .Sp
1042 This is typically used when testing cannot continue such as a critical
1043 module failing to compile or a necessary external utility not being
1044 available such as a database connection failing.
1045 .Sp
1046 The test will exit with 255.
1047 .Sp
1048 For even better control look at Test::Most.
1049 .SS "Discouraged comparison functions"
1050 .IX Subsection "Discouraged comparison functions"
1051 The use of the following functions is discouraged as they are not
1052 actually testing functions and produce no diagnostics to help figure
1053 out what went wrong. They were written before \f(CWis_deeply()\fR existed
1054 because I couldn\*(Aqt figure out how to display a useful diff of two
1055 arbitrary data structures.
1056 .PP
1057 These functions are usually used inside an \f(CWok()\fR.
1058 .PP
1059 .Vb 1
1060 \& ok( eq_array(\e@got, \e@expected) );
1061 .Ve
1062 .PP
1063 \&\f(CWis_deeply()\fR can do that better and with diagnostics.
1064 .PP
1065 .Vb 1
1066 \& is_deeply( \e@got, \e@expected );
1067 .Ve
1068 .PP
1069 They may be deprecated in future versions.
1070 .IP \fBeq_array\fR 4
1071 .IX Item "eq_array"
1072 .Vb 1
1073 \& my $is_eq = eq_array(\e@got, \e@expected);
1074 .Ve
1075 .Sp
1076 Checks if two arrays are equivalent. This is a deep check, so
1077 multi\-level structures are handled correctly.
1078 .IP \fBeq_hash\fR 4
1079 .IX Item "eq_hash"
1080 .Vb 1
1081 \& my $is_eq = eq_hash(\e%got, \e%expected);
1082 .Ve
1083 .Sp
1084 Determines if the two hashes contain the same keys and values. This
1085 is a deep check.
1086 .IP \fBeq_set\fR 4
1087 .IX Item "eq_set"
1088 .Vb 1
1089 \& my $is_eq = eq_set(\e@got, \e@expected);
1090 .Ve
1091 .Sp
1092 Similar to \f(CWeq_array()\fR, except the order of the elements is \fBnot\fR
1093 important. This is a deep check, but the irrelevancy of order only
1094 applies to the top level.
1095 .Sp
1096 .Vb 1
1097 \& ok( eq_set(\e@got, \e@expected) );
1098 .Ve
1099 .Sp
1100 Is better written:
1101 .Sp
1102 .Vb 1
1103 \& is_deeply( [sort @got], [sort @expected] );
1104 .Ve
1105 .Sp
1106 \&\fBNOTE\fR By historical accident, this is not a true set comparison.
1107 While the order of elements does not matter, duplicate elements do.
1108 .Sp
1109 \&\fBNOTE\fR \f(CWeq_set()\fR does not know how to deal with references at the top
1110 level. The following is an example of a comparison which might not work:
1111 .Sp
1112 .Vb 1
1113 \& eq_set([\e1, \e2], [\e2, \e1]);
1114 .Ve
1115 .Sp
1116 Test::Deep contains much better set comparison functions.
1117 .SS "Extending and Embedding Test::More"
1118 .IX Subsection "Extending and Embedding Test::More"
1119 Sometimes the Test::More interface isn\*(Aqt quite enough. Fortunately,
1120 Test::More is built on top of Test::Builder which provides a single,
1121 unified backend for any test library to use. This means two test
1122 libraries which both use Test::Builder \fBcan\fR be used together in the
1123 same program.
1124 .PP
1125 If you simply want to do a little tweaking of how the tests behave,
1126 you can access the underlying Test::Builder object like so:
1127 .IP \fBbuilder\fR 4
1128 .IX Item "builder"
1129 .Vb 1
1130 \& my $test_builder = Test::More\->builder;
1131 .Ve
1132 .Sp
1133 Returns the Test::Builder object underlying Test::More for you to play
1134 with.
1135 .SH "EXIT CODES"
1136 .IX Header "EXIT CODES"
1137 If all your tests passed, Test::Builder will exit with zero (which is
1138 normal). If anything failed it will exit with how many failed. If
1139 you run less (or more) tests than you planned, the missing (or extras)
1140 will be considered failures. If no tests were ever run Test::Builder
1141 will throw a warning and exit with 255. If the test died, even after
1142 having successfully completed all its tests, it will still be
1143 considered a failure and will exit with 255.
1144 .PP
1145 So the exit codes are...
1146 .PP
1147 .Vb 3
1148 \& 0 all tests successful
1149 \& 255 test died or all passed but wrong # of tests run
1150 \& any other number how many failed (including missing or extras)
1151 .Ve
1152 .PP
1153 If you fail more than 254 tests, it will be reported as 254.
1154 .PP
1155 \&\fBNOTE\fR This behavior may go away in future versions.
1156 .SH COMPATIBILITY
1157 .IX Header "COMPATIBILITY"
1158 Test::More works with Perls as old as 5.8.1.
1159 .PP
1160 Thread support is not very reliable before 5.10.1, but that\*(Aqs
1161 because threads are not very reliable before 5.10.1.
1162 .PP
1163 Although Test::More has been a core module in versions of Perl since 5.6.2, Test::More has evolved since then, and not all of the features you\*(Aqre used to will be present in the shipped version of Test::More. If you are writing a module, don\*(Aqt forget to indicate in your package metadata the minimum version of Test::More that you require. For instance, if you want to use \f(CWdone_testing()\fR but want your test script to run on Perl 5.10.0, you will need to explicitly require Test::More > 0.88.
1164 .PP
1165 Key feature milestones include:
1166 .IP subtests 4
1167 .IX Item "subtests"
1168 Subtests were released in Test::More 0.94, which came with Perl 5.12.0. Subtests did not implicitly call \f(CWdone_testing()\fR until 0.96; the first Perl with that fix was Perl 5.14.0 with 0.98.
1169 .ie n .IP done_testing() 4
1170 .el .IP \f(CWdone_testing()\fR 4
1171 .IX Item "done_testing()"
1172 This was released in Test::More 0.88 and first shipped with Perl in 5.10.1 as part of Test::More 0.92.
1173 .ie n .IP cmp_ok() 4
1174 .el .IP \f(CWcmp_ok()\fR 4
1175 .IX Item "cmp_ok()"
1176 Although \f(CWcmp_ok()\fR was introduced in 0.40, 0.86 fixed an important bug to make it safe for overloaded objects; the fixed first shipped with Perl in 5.10.1 as part of Test::More 0.92.
1177 .ie n .IP "new_ok() note() and explain()" 4
1178 .el .IP "\f(CWnew_ok()\fR \f(CWnote()\fR and \f(CWexplain()\fR" 4
1179 .IX Item "new_ok() note() and explain()"
1180 These were was released in Test::More 0.82, and first shipped with Perl in 5.10.1 as part of Test::More 0.92.
1181 .PP
1182 There is a full version history in the Changes file, and the Test::More versions included as core can be found using Module::CoreList:
1183 .PP
1184 .Vb 1
1185 \& $ corelist \-a Test::More
1186 .Ve
1187 .SH "CAVEATS and NOTES"
1188 .IX Header "CAVEATS and NOTES"
1189 .IP "UTF\-8 / ""Wide character in print""" 4
1190 .IX Item "UTF-8 / ""Wide character in print"""
1191 If you use UTF\-8 or other non\-ASCII characters with Test::More you
1192 might get a "Wide character in print" warning. Using
1193 \&\f(CW\*(C`binmode STDOUT, ":utf8"\*(C'\fR will not fix it.
1194 Test::Builder (which powers
1195 Test::More) duplicates STDOUT and STDERR. So any changes to them,
1196 including changing their output disciplines, will not be seen by
1197 Test::More.
1198 .Sp
1199 One work around is to apply encodings to STDOUT and STDERR as early
1200 as possible and before Test::More (or any other Test module) loads.
1201 .Sp
1202 .Vb 2
1203 \& use open \*(Aq:std\*(Aq, \*(Aq:encoding(UTF\-8)\*(Aq;
1204 \& use Test::More;
1205 .Ve
1206 .Sp
1207 A more direct work around is to change the filehandles used by
1208 Test::Builder.
1209 .Sp
1210 .Vb 4
1211 \& my $builder = Test::More\->builder;
1212 \& binmode $builder\->output, ":encoding(UTF\-8)";
1213 \& binmode $builder\->failure_output, ":encoding(UTF\-8)";
1214 \& binmode $builder\->todo_output, ":encoding(UTF\-8)";
1215 .Ve
1216 .IP "Overloaded objects" 4
1217 .IX Item "Overloaded objects"
1218 String overloaded objects are compared \fBas strings\fR (or in \f(CWcmp_ok()\fR\*(Aqs
1219 case, strings or numbers as appropriate to the comparison op). This
1220 prevents Test::More from piercing an object\*(Aqs interface allowing
1221 better blackbox testing. So if a function starts returning overloaded
1222 objects instead of bare strings your tests won\*(Aqt notice the
1223 difference. This is good.
1224 .Sp
1225 However, it does mean that functions like \f(CWis_deeply()\fR cannot be used to
1226 test the internals of string overloaded objects. In this case I would
1227 suggest Test::Deep which contains more flexible testing functions for
1228 complex data structures.
1229 .IP Threads 4
1230 .IX Item "Threads"
1231 Test::More will only be aware of threads if \f(CW\*(C`use threads\*(C'\fR has been done
1232 \&\fIbefore\fR Test::More is loaded. This is ok:
1233 .Sp
1234 .Vb 2
1235 \& use threads;
1236 \& use Test::More;
1237 .Ve
1238 .Sp
1239 This may cause problems:
1240 .Sp
1241 .Vb 2
1242 \& use Test::More
1243 \& use threads;
1244 .Ve
1245 .Sp
1246 5.8.1 and above are supported. Anything below that has too many bugs.
1247 .SH HISTORY
1248 .IX Header "HISTORY"
1249 This is a case of convergent evolution with Joshua Pritikin\*(Aqs Test
1250 module. I was largely unaware of its existence when I\*(Aqd first
1251 written my own \f(CWok()\fR routines. This module exists because I can\*(Aqt
1252 figure out how to easily wedge test names into Test\*(Aqs interface (along
1253 with a few other problems).
1254 .PP
1255 The goal here is to have a testing utility that\*(Aqs simple to learn,
1256 quick to use and difficult to trip yourself up with while still
1257 providing more flexibility than the existing Test.pm. As such, the
1258 names of the most common routines are kept tiny, special cases and
1259 magic side\-effects are kept to a minimum. WYSIWYG.
1260 .SH "SEE ALSO"
1261 .IX Header "SEE ALSO"
1262 .SS ""
1263 .IX Subsection ""
1264 .SS ALTERNATIVES
1265 .IX Subsection "ALTERNATIVES"
1266 Test2::Suite is the most recent and modern set of tools for testing.
1267 .PP
1268 Test::Simple if all this confuses you and you just want to write
1269 some tests. You can upgrade to Test::More later (it\*(Aqs forward
1270 compatible).
1271 .PP
1272 Test::Legacy tests written with Test.pm, the original testing
1273 module, do not play well with other testing libraries. Test::Legacy
1274 emulates the Test.pm interface and does play well with others.
1275 .SS "ADDITIONAL LIBRARIES"
1276 .IX Subsection "ADDITIONAL LIBRARIES"
1277 Test::Differences for more ways to test complex data structures.
1278 And it plays well with Test::More.
1279 .PP
1280 Test::Class is like xUnit but more perlish.
1281 .PP
1282 Test::Deep gives you more powerful complex data structure testing.
1283 .PP
1284 Test::Inline shows the idea of embedded testing.
1285 .PP
1286 Mock::Quick The ultimate mocking library. Easily spawn objects defined on
1287 the fly. Can also override, block, or reimplement packages as needed.
1288 .PP
1289 Test::FixtureBuilder Quickly define fixture data for unit tests.
1290 .SS "OTHER COMPONENTS"
1291 .IX Subsection "OTHER COMPONENTS"
1292 Test::Harness is the test runner and output interpreter for Perl.
1293 It\*(Aqs the thing that powers \f(CW\*(C`make test\*(C'\fR and where the \f(CW\*(C`prove\*(C'\fR utility
1294 comes from.
1295 .SS BUNDLES
1296 .IX Subsection "BUNDLES"
1297 Test::Most Most commonly needed test functions and features.
1298 .SH "ENVIRONMENT VARIABLES"
1299 .IX Header "ENVIRONMENT VARIABLES"
1300 See Test2::Env for a list of meaningul environment variables.
1301 .SH AUTHORS
1302 .IX Header "AUTHORS"
1303 Michael G Schwern <[email protected]> with much inspiration
1304 from Joshua Pritikin\*(Aqs Test module and lots of help from Barrie
1305 Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and
1306 the perl\-qa gang.
1307 .SH MAINTAINERS
1308 .IX Header "MAINTAINERS"
1309 .IP "Chad Granum <[email protected]>" 4
1310 .IX Item "Chad Granum <[email protected]>"
1311 .SH BUGS
1312 .IX Header "BUGS"
1313 See <https://github.com/Test\-More/test\-more/issues> to report and view bugs.
1314 .SH SOURCE
1315 .IX Header "SOURCE"
1316 The source code repository for Test::More can be found at
1317 <https://github.com/Test\-More/test\-more/>.
1318 .SH COPYRIGHT
1319 .IX Header "COPYRIGHT"
1320 Copyright 2001\-2008 by Michael G Schwern <[email protected]>.
1321 .PP
1322 This program is free software; you can redistribute it and/or
1323 modify it under the same terms as Perl itself.
1324 .PP
1325 See <https://dev.perl.org/licenses/>