Test::More(3pm)

1Test::More(3)         User Contributed Perl Documentation        Test::More(3)
2
3
4

NAME

6       Test::More - yet another framework for writing test scripts
7

SYNOPSIS

9         use Test::More tests => 23;
10         # or
11         use Test::More skip_all => $reason;
12         # or
13         use Test::More;   # see done_testing()
14
15         require_ok( 'Some::Module' );
16
17         # Various ways to say "ok"
18         ok($got eq $expected, $test_name);
19
20         is  ($got, $expected, $test_name);
21         isnt($got, $expected, $test_name);
22
23         # Rather than print STDERR "# here's what went wrong\n"
24         diag("here's what went wrong");
25
26         like  ($got, qr/expected/, $test_name);
27         unlike($got, qr/expected/, $test_name);
28
29         cmp_ok($got, '==', $expected, $test_name);
30
31         is_deeply($got_complex_structure, $expected_complex_structure, $test_name);
32
33         SKIP: {
34             skip $why, $how_many unless $have_some_feature;
35
36             ok( foo(),       $test_name );
37             is( foo(42), 23, $test_name );
38         };
39
40         TODO: {
41             local $TODO = $why;
42
43             ok( foo(),       $test_name );
44             is( foo(42), 23, $test_name );
45         };
46
47         can_ok($module, @methods);
48         isa_ok($object, $class);
49
50         pass($test_name);
51         fail($test_name);
52
53         BAIL_OUT($why);
54
55         # UNIMPLEMENTED!!!
56         my @status = Test::More::status;
57

DESCRIPTION

59       STOP! If you're just getting started writing tests, have a look at
60       Test2::Suite first.
61
62       This is a drop in replacement for Test::Simple which you can switch to
63       once you get the hang of basic testing.
64
65       The purpose of this module is to provide a wide range of testing
66       utilities.  Various ways to say "ok" with better diagnostics,
67       facilities to skip tests, test future features and compare complicated
68       data structures.  While you can do almost anything with a simple "ok()"
69       function, it doesn't provide good diagnostic output.
70
71   I love it when a plan comes together
72       Before anything else, you need a testing plan.  This basically declares
73       how many tests your script is going to run to protect against premature
74       failure.
75
76       The preferred way to do this is to declare a plan when you "use
77       Test::More".
78
79         use Test::More tests => 23;
80
81       There are cases when you will not know beforehand how many tests your
82       script is going to run.  In this case, you can declare your tests at
83       the end.
84
85         use Test::More;
86
87         ... run your tests ...
88
89         done_testing( $number_of_tests_run );
90
91       NOTE "done_testing()" should never be called in an "END { ... }" block.
92
93       Sometimes you really don't know how many tests were run, or it's too
94       difficult to calculate.  In which case you can leave off
95       $number_of_tests_run.
96
97       In some cases, you'll want to completely skip an entire testing script.
98
99         use Test::More skip_all => $skip_reason;
100
101       Your script will declare a skip with the reason why you skipped and
102       exit immediately with a zero (success).  See Test::Harness for details.
103
104       If you want to control what functions Test::More will export, you have
105       to use the 'import' option.  For example, to import everything but
106       'fail', you'd do:
107
108         use Test::More tests => 23, import => ['!fail'];
109
110       Alternatively, you can use the "plan()" function.  Useful for when you
111       have to calculate the number of tests.
112
113         use Test::More;
114         plan tests => keys %Stuff * 3;
115
116       or for deciding between running the tests at all:
117
118         use Test::More;
119         if( $^O eq 'MacOS' ) {
120             plan skip_all => 'Test irrelevant on MacOS';
121         }
122         else {
123             plan tests => 42;
124         }
125
126       done_testing
127               done_testing();
128               done_testing($number_of_tests);
129
130           If you don't know how many tests you're going to run, you can issue
131           the plan when you're done running tests.
132
133           $number_of_tests is the same as "plan()", it's the number of tests
134           you expected to run.  You can omit this, in which case the number
135           of tests you ran doesn't matter, just the fact that your tests ran
136           to conclusion.
137
138           This is safer than and replaces the "no_plan" plan.
139
140           Note: You must never put "done_testing()" inside an "END { ... }"
141           block.  The plan is there to ensure your test does not exit before
142           testing has completed. If you use an END block you completely
143           bypass this protection.
144
145   Test names
146       By convention, each test is assigned a number in order.  This is
147       largely done automatically for you.  However, it's often very useful to
148       assign a name to each test.  Which would you rather see:
149
150         ok 4
151         not ok 5
152         ok 6
153
154       or
155
156         ok 4 - basic multi-variable
157         not ok 5 - simple exponential
158         ok 6 - force == mass * acceleration
159
160       The later gives you some idea of what failed.  It also makes it easier
161       to find the test in your script, simply search for "simple
162       exponential".
163
164       All test functions take a name argument.  It's optional, but highly
165       suggested that you use it.
166
167   I'm ok, you're not ok.
168       The basic purpose of this module is to print out either "ok #" or "not
169       ok #" depending on if a given test succeeded or failed.  Everything
170       else is just gravy.
171
172       All of the following print "ok" or "not ok" depending on if the test
173       succeeded or failed.  They all also return true or false, respectively.
174
175       ok
176             ok($got eq $expected, $test_name);
177
178           This simply evaluates any expression ("$got eq $expected" is just a
179           simple example) and uses that to determine if the test succeeded or
180           failed.  A true expression passes, a false one fails.  Very simple.
181
182           For example:
183
184               ok( $exp{9} == 81,                   'simple exponential' );
185               ok( Film->can('db_Main'),            'set_db()' );
186               ok( $p->tests == 4,                  'saw tests' );
187               ok( !grep(!defined $_, @items),      'all items defined' );
188
189           (Mnemonic:  "This is ok.")
190
191           $test_name is a very short description of the test that will be
192           printed out.  It makes it very easy to find a test in your script
193           when it fails and gives others an idea of your intentions.
194           $test_name is optional, but we very strongly encourage its use.
195
196           Should an "ok()" fail, it will produce some diagnostics:
197
198               not ok 18 - sufficient mucus
199               #   Failed test 'sufficient mucus'
200               #   in foo.t at line 42.
201
202           This is the same as Test::Simple's "ok()" routine.
203
204       is
205       isnt
206             is  ( $got, $expected, $test_name );
207             isnt( $got, $expected, $test_name );
208
209           Similar to "ok()", "is()" and "isnt()" compare their two arguments
210           with "eq" and "ne" respectively and use the result of that to
211           determine if the test succeeded or failed.  So these:
212
213               # Is the ultimate answer 42?
214               is( ultimate_answer(), 42,          "Meaning of Life" );
215
216               # $foo isn't empty
217               isnt( $foo, '',     "Got some foo" );
218
219           are similar to these:
220
221               ok( ultimate_answer() eq 42,        "Meaning of Life" );
222               ok( $foo ne '',     "Got some foo" );
223
224           "undef" will only ever match "undef".  So you can test a value
225           against "undef" like this:
226
227               is($not_defined, undef, "undefined as expected");
228
229           (Mnemonic:  "This is that."  "This isn't that.")
230
231           So why use these?  They produce better diagnostics on failure.
232           "ok()" cannot know what you are testing for (beyond the name), but
233           "is()" and "isnt()" know what the test was and why it failed.  For
234           example this test:
235
236               my $foo = 'waffle';  my $bar = 'yarblokos';
237               is( $foo, $bar,   'Is foo the same as bar?' );
238
239           Will produce something like this:
240
241               not ok 17 - Is foo the same as bar?
242               #   Failed test 'Is foo the same as bar?'
243               #   in foo.t at line 139.
244               #          got: 'waffle'
245               #     expected: 'yarblokos'
246
247           So you can figure out what went wrong without rerunning the test.
248
249           You are encouraged to use "is()" and "isnt()" over "ok()" where
250           possible, however do not be tempted to use them to find out if
251           something is true or false!
252
253             # XXX BAD!
254             is( exists $brooklyn{tree}, 1, 'A tree grows in Brooklyn' );
255
256           This does not check if "exists $brooklyn{tree}" is true, it checks
257           if it returns 1.  Very different.  Similar caveats exist for false
258           and 0.  In these cases, use "ok()".
259
260             ok( exists $brooklyn{tree},    'A tree grows in Brooklyn' );
261
262           A simple call to "isnt()" usually does not provide a strong test
263           but there are cases when you cannot say much more about a value
264           than that it is different from some other value:
265
266             new_ok $obj, "Foo";
267
268             my $clone = $obj->clone;
269             isa_ok $obj, "Foo", "Foo->clone";
270
271             isnt $obj, $clone, "clone() produces a different object";
272
273           For those grammatical pedants out there, there's an "isn't()"
274           function which is an alias of "isnt()".
275
276       like
277             like( $got, qr/expected/, $test_name );
278
279           Similar to "ok()", "like()" matches $got against the regex
280           "qr/expected/".
281
282           So this:
283
284               like($got, qr/expected/, 'this is like that');
285
286           is similar to:
287
288               ok( $got =~ m/expected/, 'this is like that');
289
290           (Mnemonic "This is like that".)
291
292           The second argument is a regular expression.  It may be given as a
293           regex reference (i.e. "qr//") or (for better compatibility with
294           older perls) as a string that looks like a regex (alternative
295           delimiters are currently not supported):
296
297               like( $got, '/expected/', 'this is like that' );
298
299           Regex options may be placed on the end ('/expected/i').
300
301           Its advantages over "ok()" are similar to that of "is()" and
302           "isnt()".  Better diagnostics on failure.
303
304       unlike
305             unlike( $got, qr/expected/, $test_name );
306
307           Works exactly as "like()", only it checks if $got does not match
308           the given pattern.
309
310       cmp_ok
311             cmp_ok( $got, $op, $expected, $test_name );
312
313           Halfway between "ok()" and "is()" lies "cmp_ok()".  This allows you
314           to compare two arguments using any binary perl operator.  The test
315           passes if the comparison is true and fails otherwise.
316
317               # ok( $got eq $expected );
318               cmp_ok( $got, 'eq', $expected, 'this eq that' );
319
320               # ok( $got == $expected );
321               cmp_ok( $got, '==', $expected, 'this == that' );
322
323               # ok( $got && $expected );
324               cmp_ok( $got, '&&', $expected, 'this && that' );
325               ...etc...
326
327           Its advantage over "ok()" is when the test fails you'll know what
328           $got and $expected were:
329
330               not ok 1
331               #   Failed test in foo.t at line 12.
332               #     '23'
333               #         &&
334               #     undef
335
336           It's also useful in those cases where you are comparing numbers and
337           "is()"'s use of "eq" will interfere:
338
339               cmp_ok( $big_hairy_number, '==', $another_big_hairy_number );
340
341           It's especially useful when comparing greater-than or smaller-than
342           relation between values:
343
344               cmp_ok( $some_value, '<=', $upper_limit );
345
346       can_ok
347             can_ok($module, @methods);
348             can_ok($object, @methods);
349
350           Checks to make sure the $module or $object can do these @methods
351           (works with functions, too).
352
353               can_ok('Foo', qw(this that whatever));
354
355           is almost exactly like saying:
356
357               ok( Foo->can('this') &&
358                   Foo->can('that') &&
359                   Foo->can('whatever')
360                 );
361
362           only without all the typing and with a better interface.  Handy for
363           quickly testing an interface.
364
365           No matter how many @methods you check, a single "can_ok()" call
366           counts as one test.  If you desire otherwise, use:
367
368               foreach my $meth (@methods) {
369                   can_ok('Foo', $meth);
370               }
371
372       isa_ok
373             isa_ok($object,   $class, $object_name);
374             isa_ok($subclass, $class, $object_name);
375             isa_ok($ref,      $type,  $ref_name);
376
377           Checks to see if the given "$object->isa($class)".  Also checks to
378           make sure the object was defined in the first place.  Handy for
379           this sort of thing:
380
381               my $obj = Some::Module->new;
382               isa_ok( $obj, 'Some::Module' );
383
384           where you'd otherwise have to write
385
386               my $obj = Some::Module->new;
387               ok( defined $obj && $obj->isa('Some::Module') );
388
389           to safeguard against your test script blowing up.
390
391           You can also test a class, to make sure that it has the right
392           ancestor:
393
394               isa_ok( 'Vole', 'Rodent' );
395
396           It works on references, too:
397
398               isa_ok( $array_ref, 'ARRAY' );
399
400           The diagnostics of this test normally just refer to 'the object'.
401           If you'd like them to be more specific, you can supply an
402           $object_name (for example 'Test customer').
403
404       new_ok
405             my $obj = new_ok( $class );
406             my $obj = new_ok( $class => \@args );
407             my $obj = new_ok( $class => \@args, $object_name );
408
409           A convenience function which combines creating an object and
410           calling "isa_ok()" on that object.
411
412           It is basically equivalent to:
413
414               my $obj = $class->new(@args);
415               isa_ok $obj, $class, $object_name;
416
417           If @args is not given, an empty list will be used.
418
419           This function only works on "new()" and it assumes "new()" will
420           return just a single object which isa $class.
421
422       subtest
423               subtest $name => \&code, @args;
424
425           "subtest()" runs the &code as its own little test with its own plan
426           and its own result.  The main test counts this as a single test
427           using the result of the whole subtest to determine if its ok or not
428           ok.
429
430           For example...
431
432             use Test::More tests => 3;
433
434             pass("First test");
435
436             subtest 'An example subtest' => sub {
437                 plan tests => 2;
438
439                 pass("This is a subtest");
440                 pass("So is this");
441             };
442
443             pass("Third test");
444
445           This would produce.
446
447             1..3
448             ok 1 - First test
449                 # Subtest: An example subtest
450                 1..2
451                 ok 1 - This is a subtest
452                 ok 2 - So is this
453             ok 2 - An example subtest
454             ok 3 - Third test
455
456           A subtest may call "skip_all".  No tests will be run, but the
457           subtest is considered a skip.
458
459             subtest 'skippy' => sub {
460                 plan skip_all => 'cuz I said so';
461                 pass('this test will never be run');
462             };
463
464           Returns true if the subtest passed, false otherwise.
465
466           Due to how subtests work, you may omit a plan if you desire.  This
467           adds an implicit "done_testing()" to the end of your subtest.  The
468           following two subtests are equivalent:
469
470             subtest 'subtest with implicit done_testing()', sub {
471                 ok 1, 'subtests with an implicit done testing should work';
472                 ok 1, '... and support more than one test';
473                 ok 1, '... no matter how many tests are run';
474             };
475
476             subtest 'subtest with explicit done_testing()', sub {
477                 ok 1, 'subtests with an explicit done testing should work';
478                 ok 1, '... and support more than one test';
479                 ok 1, '... no matter how many tests are run';
480                 done_testing();
481             };
482
483           Extra arguments given to "subtest" are passed to the callback. For
484           example:
485
486               sub my_subtest {
487                   my $range = shift;
488                   ...
489               }
490
491               for my $range (1, 10, 100, 1000) {
492                   subtest "testing range $range", \&my_subtest, $range;
493               }
494
495       pass
496       fail
497             pass($test_name);
498             fail($test_name);
499
500           Sometimes you just want to say that the tests have passed.  Usually
501           the case is you've got some complicated condition that is difficult
502           to wedge into an "ok()".  In this case, you can simply use "pass()"
503           (to declare the test ok) or fail (for not ok).  They are synonyms
504           for ok(1) and ok(0).
505
506           Use these very, very, very sparingly.
507
508   Module tests
509       Sometimes you want to test if a module, or a list of modules, can
510       successfully load.  For example, you'll often want a first test which
511       simply loads all the modules in the distribution to make sure they work
512       before going on to do more complicated testing.
513
514       For such purposes we have "use_ok" and "require_ok".
515
516       require_ok
517              require_ok($module);
518              require_ok($file);
519
520           Tries to "require" the given $module or $file.  If it loads
521           successfully, the test will pass.  Otherwise it fails and displays
522           the load error.
523
524           "require_ok" will guess whether the input is a module name or a
525           filename.
526
527           No exception will be thrown if the load fails.
528
529               # require Some::Module
530               require_ok "Some::Module";
531
532               # require "Some/File.pl";
533               require_ok "Some/File.pl";
534
535               # stop testing if any of your modules will not load
536               for my $module (@module) {
537                   require_ok $module or BAIL_OUT "Can't load $module";
538               }
539
540       use_ok
541              BEGIN { use_ok($module); }
542              BEGIN { use_ok($module, @imports); }
543
544           Like "require_ok", but it will "use" the $module in question and
545           only loads modules, not files.
546
547           If you just want to test a module can be loaded, use "require_ok".
548
549           If you just want to load a module in a test, we recommend simply
550           using "use" directly.  It will cause the test to stop.
551
552           It's recommended that you run "use_ok()" inside a BEGIN block so
553           its functions are exported at compile-time and prototypes are
554           properly honored.
555
556           If @imports are given, they are passed through to the use.  So
557           this:
558
559              BEGIN { use_ok('Some::Module', qw(foo bar)) }
560
561           is like doing this:
562
563              use Some::Module qw(foo bar);
564
565           Version numbers can be checked like so:
566
567              # Just like "use Some::Module 1.02"
568              BEGIN { use_ok('Some::Module', 1.02) }
569
570           Don't try to do this:
571
572              BEGIN {
573                  use_ok('Some::Module');
574
575                  ...some code that depends on the use...
576                  ...happening at compile time...
577              }
578
579           because the notion of "compile-time" is relative.  Instead, you
580           want:
581
582             BEGIN { use_ok('Some::Module') }
583             BEGIN { ...some code that depends on the use... }
584
585           If you want the equivalent of "use Foo ()", use a module but not
586           import anything, use "require_ok".
587
588             BEGIN { require_ok "Foo" }
589
590   Complex data structures
591       Not everything is a simple eq check or regex.  There are times you need
592       to see if two data structures are equivalent.  For these instances
593       Test::More provides a handful of useful functions.
594
595       NOTE I'm not quite sure what will happen with filehandles.
596
597       is_deeply
598             is_deeply( $got, $expected, $test_name );
599
600           Similar to "is()", except that if $got and $expected are
601           references, it does a deep comparison walking each data structure
602           to see if they are equivalent.  If the two structures are
603           different, it will display the place where they start differing.
604
605           "is_deeply()" compares the dereferenced values of references, the
606           references themselves (except for their type) are ignored.  This
607           means aspects such as blessing and ties are not considered
608           "different".
609
610           "is_deeply()" currently has very limited handling of function
611           reference and globs.  It merely checks if they have the same
612           referent.  This may improve in the future.
613
614           Test::Differences and Test::Deep provide more in-depth
615           functionality along these lines.
616
617           NOTE is_deeply() has limitations when it comes to comparing strings
618           and refs:
619
620               my $path = path('.');
621               my $hash = {};
622               is_deeply( $path, "$path" ); # ok
623               is_deeply( $hash, "$hash" ); # fail
624
625           This happens because is_deeply will unoverload all arguments
626           unconditionally.  It is probably best not to use is_deeply with
627           overloading. For legacy reasons this is not likely to ever be
628           fixed. If you would like a much better tool for this you should see
629           Test2::Suite Specifically Test2::Tools::Compare has an "is()"
630           function that works like "is_deeply" with many improvements.
631
632   Diagnostics
633       If you pick the right test function, you'll usually get a good idea of
634       what went wrong when it failed.  But sometimes it doesn't work out that
635       way.  So here we have ways for you to write your own diagnostic
636       messages which are safer than just "print STDERR".
637
638       diag
639             diag(@diagnostic_message);
640
641           Prints a diagnostic message which is guaranteed not to interfere
642           with test output.  Like "print" @diagnostic_message is simply
643           concatenated together.
644
645           Returns false, so as to preserve failure.
646
647           Handy for this sort of thing:
648
649               ok( grep(/foo/, @users), "There's a foo user" ) or
650                   diag("Since there's no foo, check that /etc/bar is set up right");
651
652           which would produce:
653
654               not ok 42 - There's a foo user
655               #   Failed test 'There's a foo user'
656               #   in foo.t at line 52.
657               # Since there's no foo, check that /etc/bar is set up right.
658
659           You might remember "ok() or diag()" with the mnemonic "open() or
660           die()".
661
662           NOTE The exact formatting of the diagnostic output is still
663           changing, but it is guaranteed that whatever you throw at it won't
664           interfere with the test.
665
666       note
667             note(@diagnostic_message);
668
669           Like "diag()", except the message will not be seen when the test is
670           run in a harness.  It will only be visible in the verbose TAP
671           stream.
672
673           Handy for putting in notes which might be useful for debugging, but
674           don't indicate a problem.
675
676               note("Tempfile is $tempfile");
677
678       explain
679             my @dump = explain @diagnostic_message;
680
681           Will dump the contents of any references in a human readable
682           format.  Usually you want to pass this into "note" or "diag".
683
684           Handy for things like...
685
686               is_deeply($have, $want) || diag explain $have;
687
688           or
689
690               note explain \%args;
691               Some::Class->method(%args);
692
693   Conditional tests
694       Sometimes running a test under certain conditions will cause the test
695       script to die.  A certain function or method isn't implemented (such as
696       "fork()" on MacOS), some resource isn't available (like a net
697       connection) or a module isn't available.  In these cases it's necessary
698       to skip tests, or declare that they are supposed to fail but will work
699       in the future (a todo test).
700
701       For more details on the mechanics of skip and todo tests see
702       Test::Harness.
703
704       The way Test::More handles this is with a named block.  Basically, a
705       block of tests which can be skipped over or made todo.  It's best if I
706       just show you...
707
708       SKIP: BLOCK
709             SKIP: {
710                 skip $why, $how_many if $condition;
711
712                 ...normal testing code goes here...
713             }
714
715           This declares a block of tests that might be skipped, $how_many
716           tests there are, $why and under what $condition to skip them.  An
717           example is the easiest way to illustrate:
718
719               SKIP: {
720                   eval { require HTML::Lint };
721
722                   skip "HTML::Lint not installed", 2 if $@;
723
724                   my $lint = new HTML::Lint;
725                   isa_ok( $lint, "HTML::Lint" );
726
727                   $lint->parse( $html );
728                   is( $lint->errors, 0, "No errors found in HTML" );
729               }
730
731           If the user does not have HTML::Lint installed, the whole block of
732           code won't be run at all.  Test::More will output special ok's
733           which Test::Harness interprets as skipped, but passing, tests.
734
735           It's important that $how_many accurately reflects the number of
736           tests in the SKIP block so the # of tests run will match up with
737           your plan.  If your plan is "no_plan" $how_many is optional and
738           will default to 1.
739
740           It's perfectly safe to nest SKIP blocks.  Each SKIP block must have
741           the label "SKIP", or Test::More can't work its magic.
742
743           You don't skip tests which are failing because there's a bug in
744           your program, or for which you don't yet have code written.  For
745           that you use TODO.  Read on.
746
747       TODO: BLOCK
748               TODO: {
749                   local $TODO = $why if $condition;
750
751                   ...normal testing code goes here...
752               }
753
754           Declares a block of tests you expect to fail and $why.  Perhaps
755           it's because you haven't fixed a bug or haven't finished a new
756           feature:
757
758               TODO: {
759                   local $TODO = "URI::Geller not finished";
760
761                   my $card = "Eight of clubs";
762                   is( URI::Geller->your_card, $card, 'Is THIS your card?' );
763
764                   my $spoon;
765                   URI::Geller->bend_spoon;
766                   is( $spoon, 'bent',    "Spoon bending, that's original" );
767               }
768
769           With a todo block, the tests inside are expected to fail.
770           Test::More will run the tests normally, but print out special flags
771           indicating they are "todo".  Test::Harness will interpret failures
772           as being ok.  Should anything succeed, it will report it as an
773           unexpected success.  You then know the thing you had todo is done
774           and can remove the TODO flag.
775
776           The nice part about todo tests, as opposed to simply commenting out
777           a block of tests, is it's like having a programmatic todo list.
778           You know how much work is left to be done, you're aware of what
779           bugs there are, and you'll know immediately when they're fixed.
780
781           Once a todo test starts succeeding, simply move it outside the
782           block.  When the block is empty, delete it.
783
784       todo_skip
785               TODO: {
786                   todo_skip $why, $how_many if $condition;
787
788                   ...normal testing code...
789               }
790
791           With todo tests, it's best to have the tests actually run.  That
792           way you'll know when they start passing.  Sometimes this isn't
793           possible.  Often a failing test will cause the whole program to die
794           or hang, even inside an "eval BLOCK" with and using "alarm".  In
795           these extreme cases you have no choice but to skip over the broken
796           tests entirely.
797
798           The syntax and behavior is similar to a "SKIP: BLOCK" except the
799           tests will be marked as failing but todo.  Test::Harness will
800           interpret them as passing.
801
802       When do I use SKIP vs. TODO?
803           If it's something the user might not be able to do, use SKIP.  This
804           includes optional modules that aren't installed, running under an
805           OS that doesn't have some feature (like "fork()" or symlinks), or
806           maybe you need an Internet connection and one isn't available.
807
808           If it's something the programmer hasn't done yet, use TODO.  This
809           is for any code you haven't written yet, or bugs you have yet to
810           fix, but want to put tests in your testing script (always a good
811           idea).
812
813   Test control
814       BAIL_OUT
815               BAIL_OUT($reason);
816
817           Indicates to the harness that things are going so badly all testing
818           should terminate.  This includes the running of any additional test
819           scripts.
820
821           This is typically used when testing cannot continue such as a
822           critical module failing to compile or a necessary external utility
823           not being available such as a database connection failing.
824
825           The test will exit with 255.
826
827           For even better control look at Test::Most.
828
829   Discouraged comparison functions
830       The use of the following functions is discouraged as they are not
831       actually testing functions and produce no diagnostics to help figure
832       out what went wrong.  They were written before "is_deeply()" existed
833       because I couldn't figure out how to display a useful diff of two
834       arbitrary data structures.
835
836       These functions are usually used inside an "ok()".
837
838           ok( eq_array(\@got, \@expected) );
839
840       "is_deeply()" can do that better and with diagnostics.
841
842           is_deeply( \@got, \@expected );
843
844       They may be deprecated in future versions.
845
846       eq_array
847             my $is_eq = eq_array(\@got, \@expected);
848
849           Checks if two arrays are equivalent.  This is a deep check, so
850           multi-level structures are handled correctly.
851
852       eq_hash
853             my $is_eq = eq_hash(\%got, \%expected);
854
855           Determines if the two hashes contain the same keys and values.
856           This is a deep check.
857
858       eq_set
859             my $is_eq = eq_set(\@got, \@expected);
860
861           Similar to "eq_array()", except the order of the elements is not
862           important.  This is a deep check, but the irrelevancy of order only
863           applies to the top level.
864
865               ok( eq_set(\@got, \@expected) );
866
867           Is better written:
868
869               is_deeply( [sort @got], [sort @expected] );
870
871           NOTE By historical accident, this is not a true set comparison.
872           While the order of elements does not matter, duplicate elements do.
873
874           NOTE "eq_set()" does not know how to deal with references at the
875           top level.  The following is an example of a comparison which might
876           not work:
877
878               eq_set([\1, \2], [\2, \1]);
879
880           Test::Deep contains much better set comparison functions.
881
882   Extending and Embedding Test::More
883       Sometimes the Test::More interface isn't quite enough.  Fortunately,
884       Test::More is built on top of Test::Builder which provides a single,
885       unified backend for any test library to use.  This means two test
886       libraries which both use <Test::Builder> can be used together in the
887       same program>.
888
889       If you simply want to do a little tweaking of how the tests behave, you
890       can access the underlying Test::Builder object like so:
891
892       builder
893               my $test_builder = Test::More->builder;
894
895           Returns the Test::Builder object underlying Test::More for you to
896           play with.
897

EXIT CODES

899       If all your tests passed, Test::Builder will exit with zero (which is
900       normal).  If anything failed it will exit with how many failed.  If you
901       run less (or more) tests than you planned, the missing (or extras) will
902       be considered failures.  If no tests were ever run Test::Builder will
903       throw a warning and exit with 255.  If the test died, even after having
904       successfully completed all its tests, it will still be considered a
905       failure and will exit with 255.
906
907       So the exit codes are...
908
909           0                   all tests successful
910           255                 test died or all passed but wrong # of tests run
911           any other number    how many failed (including missing or extras)
912
913       If you fail more than 254 tests, it will be reported as 254.
914
915       NOTE  This behavior may go away in future versions.
916

COMPATIBILITY

918       Test::More works with Perls as old as 5.8.1.
919
920       Thread support is not very reliable before 5.10.1, but that's because
921       threads are not very reliable before 5.10.1.
922
923       Although Test::More has been a core module in versions of Perl since
924       5.6.2, Test::More has evolved since then, and not all of the features
925       you're used to will be present in the shipped version of Test::More. If
926       you are writing a module, don't forget to indicate in your package
927       metadata the minimum version of Test::More that you require. For
928       instance, if you want to use "done_testing()" but want your test script
929       to run on Perl 5.10.0, you will need to explicitly require Test::More >
930       0.88.
931
932       Key feature milestones include:
933
934       subtests
935           Subtests were released in Test::More 0.94, which came with Perl
936           5.12.0. Subtests did not implicitly call "done_testing()" until
937           0.96; the first Perl with that fix was Perl 5.14.0 with 0.98.
938
939       "done_testing()"
940           This was released in Test::More 0.88 and first shipped with Perl in
941           5.10.1 as part of Test::More 0.92.
942
943       "cmp_ok()"
944           Although "cmp_ok()" was introduced in 0.40, 0.86 fixed an important
945           bug to make it safe for overloaded objects; the fixed first shipped
946           with Perl in 5.10.1 as part of Test::More 0.92.
947
948       "new_ok()" "note()" and "explain()"
949           These were was released in Test::More 0.82, and first shipped with
950           Perl in 5.10.1 as part of Test::More 0.92.
951
952       There is a full version history in the Changes file, and the Test::More
953       versions included as core can be found using Module::CoreList:
954
955           $ corelist -a Test::More
956

CAVEATS and NOTES

958       utf8 / "Wide character in print"
959           If you use utf8 or other non-ASCII characters with Test::More you
960           might get a "Wide character in print" warning.  Using "binmode
961           STDOUT, ":utf8"" will not fix it.  Test::Builder (which powers
962           Test::More) duplicates STDOUT and STDERR.  So any changes to them,
963           including changing their output disciplines, will not be seem by
964           Test::More.
965
966           One work around is to apply encodings to STDOUT and STDERR as early
967           as possible and before Test::More (or any other Test module) loads.
968
969               use open ':std', ':encoding(utf8)';
970               use Test::More;
971
972           A more direct work around is to change the filehandles used by
973           Test::Builder.
974
975               my $builder = Test::More->builder;
976               binmode $builder->output,         ":encoding(utf8)";
977               binmode $builder->failure_output, ":encoding(utf8)";
978               binmode $builder->todo_output,    ":encoding(utf8)";
979
980       Overloaded objects
981           String overloaded objects are compared as strings (or in
982           "cmp_ok()"'s case, strings or numbers as appropriate to the
983           comparison op).  This prevents Test::More from piercing an object's
984           interface allowing better blackbox testing.  So if a function
985           starts returning overloaded objects instead of bare strings your
986           tests won't notice the difference.  This is good.
987
988           However, it does mean that functions like "is_deeply()" cannot be
989           used to test the internals of string overloaded objects.  In this
990           case I would suggest Test::Deep which contains more flexible
991           testing functions for complex data structures.
992
993       Threads
994           Test::More will only be aware of threads if "use threads" has been
995           done before Test::More is loaded.  This is ok:
996
997               use threads;
998               use Test::More;
999
1000           This may cause problems:
1001
1002               use Test::More
1003               use threads;
1004
1005           5.8.1 and above are supported.  Anything below that has too many
1006           bugs.
1007

HISTORY

1009       This is a case of convergent evolution with Joshua Pritikin's Test
1010       module.  I was largely unaware of its existence when I'd first written
1011       my own "ok()" routines.  This module exists because I can't figure out
1012       how to easily wedge test names into Test's interface (along with a few
1013       other problems).
1014
1015       The goal here is to have a testing utility that's simple to learn,
1016       quick to use and difficult to trip yourself up with while still
1017       providing more flexibility than the existing Test.pm.  As such, the
1018       names of the most common routines are kept tiny, special cases and
1019       magic side-effects are kept to a minimum.  WYSIWYG.
1020

AUTHORS

1058       Michael G Schwern <schwern@pobox.com> with much inspiration from Joshua
1059       Pritikin's Test module and lots of help from Barrie Slaymaker, Tony
1060       Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa gang.
1061

MAINTAINERS

1063       Chad Granum <exodist@cpan.org>
1064

BUGS

1066       See https://github.com/Test-More/test-more/issues to report and view
1067       bugs.
1068

SOURCE

1070       The source code repository for Test::More can be found at
1071       http://github.com/Test-More/test-more/.
1072

COPYRIGHT

1074       Copyright 2001-2008 by Michael G Schwern <schwern@pobox.com>.
1075
1076       This program is free software; you can redistribute it and/or modify it
1077       under the same terms as Perl itself.
1078
1079       See http://www.perl.com/perl/misc/Artistic.html
1080
1081
1082
1083perl v5.30.0                      2019-09-06                     Test::More(3)