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

DESCRIPTION

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

EXIT CODES

834       If all your tests passed, Test::Builder will exit with zero (which is
835       normal).  If anything failed it will exit with how many failed.  If you
836       run less (or more) tests than you planned, the missing (or extras) will
837       be considered failures.  If no tests were ever run Test::Builder will
838       throw a warning and exit with 255.  If the test died, even after having
839       successfully completed all its tests, it will still be considered a
840       failure and will exit with 255.
841
842       So the exit codes are...
843
844           0                   all tests successful
845           255                 test died or all passed but wrong # of tests run
846           any other number    how many failed (including missing or extras)
847
848       If you fail more than 254 tests, it will be reported as 254.
849
850       NOTE  This behavior may go away in future versions.
851

CAVEATS and NOTES

853       Backwards compatibility
854           Test::More works with Perls as old as 5.6.0.
855
856       utf8 / "Wide character in print"
857           If you use utf8 or other non-ASCII characters with Test::More you
858           might get a "Wide character in print" warning.  Using "binmode
859           STDOUT, ":utf8"" will not fix it.  Test::Builder (which powers
860           Test::More) duplicates STDOUT and STDERR.  So any changes to them,
861           including changing their output disciplines, will not be seem by
862           Test::More.
863
864           The work around is to change the filehandles used by Test::Builder
865           directly.
866
867               my $builder = Test::More->builder;
868               binmode $builder->output,         ":utf8";
869               binmode $builder->failure_output, ":utf8";
870               binmode $builder->todo_output,    ":utf8";
871
872       Overloaded objects
873           String overloaded objects are compared as strings (or in cmp_ok()'s
874           case, strings or numbers as appropriate to the comparison op).
875           This prevents Test::More from piercing an object's interface
876           allowing better blackbox testing.  So if a function starts
877           returning overloaded objects instead of bare strings your tests
878           won't notice the difference.  This is good.
879
880           However, it does mean that functions like is_deeply() cannot be
881           used to test the internals of string overloaded objects.  In this
882           case I would suggest Test::Deep which contains more flexible
883           testing functions for complex data structures.
884
885       Threads
886           Test::More will only be aware of threads if "use threads" has been
887           done before Test::More is loaded.  This is ok:
888
889               use threads;
890               use Test::More;
891
892           This may cause problems:
893
894               use Test::More
895               use threads;
896
897           5.8.1 and above are supported.  Anything below that has too many
898           bugs.
899

HISTORY

901       This is a case of convergent evolution with Joshua Pritikin's Test
902       module.  I was largely unaware of its existence when I'd first written
903       my own ok() routines.  This module exists because I can't figure out
904       how to easily wedge test names into Test's interface (along with a few
905       other problems).
906
907       The goal here is to have a testing utility that's simple to learn,
908       quick to use and difficult to trip yourself up with while still
909       providing more flexibility than the existing Test.pm.  As such, the
910       names of the most common routines are kept tiny, special cases and
911       magic side-effects are kept to a minimum.  WYSIWYG.
912

SEE ALSO

914       Test::Simple if all this confuses you and you just want to write some
915       tests.  You can upgrade to Test::More later (it's forward compatible).
916
917       Test::Harness is the test runner and output interpreter for Perl.  It's
918       the thing that powers "make test" and where the "prove" utility comes
919       from.
920
921       Test::Legacy tests written with Test.pm, the original testing module,
922       do not play well with other testing libraries.  Test::Legacy emulates
923       the Test.pm interface and does play well with others.
924
925       Test::Differences for more ways to test complex data structures.  And
926       it plays well with Test::More.
927
928       Test::Class is like xUnit but more perlish.
929
930       Test::Deep gives you more powerful complex data structure testing.
931
932       Test::Inline shows the idea of embedded testing.
933
934       Bundle::Test installs a whole bunch of useful test modules.
935

AUTHORS

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

BUGS

942       See http://rt.cpan.org to report and view bugs.
943

SOURCE

945       The source code repository for Test::More can be found at
946       http://github.com/schwern/test-more/.
947
949       Copyright 2001-2008 by Michael G Schwern <schwern@pobox.com>.
950
951       This program is free software; you can redistribute it and/or modify it
952       under the same terms as Perl itself.
953
954       See http://www.perl.com/perl/misc/Artistic.html
955
956
957
958perl v5.12.3                      2011-02-23                     Test::More(3)
Impressum