1Test::More(3) User Contributed Perl Documentation Test::More(3)
2
6 Test::More - yet another framework for writing test scripts
7
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 require_ok( 'Some::Module' );
16 # Various ways to say "ok"
18 ok($got eq $expected, $test_name);
19 is ($got, $expected, $test_name);
21 isnt($got, $expected, $test_name);
22 # Rather than print STDERR "# here's what went wrong\n"
24 diag("here's what went wrong");
25 like ($got, qr/expected/, $test_name);
27 unlike($got, qr/expected/, $test_name);
28 cmp_ok($got, '==', $expected, $test_name);
30 is_deeply($got_complex_structure, $expected_complex_structure, $test_name);
32 SKIP: {
34 skip $why, $how_many unless $have_some_feature;
35 ok( foo(), $test_name );
37 is( foo(42), 23, $test_name );
38 };
39 TODO: {
41 local $TODO = $why;
42 ok( foo(), $test_name );
44 is( foo(42), 23, $test_name );
45 };
46 can_ok($module, @methods);
48 isa_ok($object, $class);
49 pass($test_name);
51 fail($test_name);
52 BAIL_OUT($why);
54 # UNIMPLEMENTED!!!
56 my @status = Test::More::status;
57
59 STOP! If you're just getting started writing tests, have a look at
60 Test::Simple first. This is a drop in replacement for Test::Simple
61 which you can switch to once you get the hang of basic testing.
62 The purpose of this module is to provide a wide range of testing
64 utilities. Various ways to say "ok" with better diagnostics,
65 facilities to skip tests, test future features and compare complicated
66 data structures. While you can do almost anything with a simple "ok()"
67 function, it doesn't provide good diagnostic output.
68 I love it when a plan comes together
70 Before anything else, you need a testing plan. This basically declares
71 how many tests your script is going to run to protect against premature
72 failure.
73 The preferred way to do this is to declare a plan when you "use
75 Test::More".
76 use Test::More tests => 23;
78 There are cases when you will not know beforehand how many tests your
80 script is going to run. In this case, you can declare your tests at
81 the end.
82 use Test::More;
84 ... run your tests ...
86 done_testing( $number_of_tests_run );
88 NOTE "done_testing()" should never be called in an "END { ... }" block.
90 Sometimes you really don't know how many tests were run, or it's too
92 difficult to calculate. In which case you can leave off
93 $number_of_tests_run.
94 In some cases, you'll want to completely skip an entire testing script.
96 use Test::More skip_all => $skip_reason;
98 Your script will declare a skip with the reason why you skipped and
100 exit immediately with a zero (success). See Test::Harness for details.
101 If you want to control what functions Test::More will export, you have
103 to use the 'import' option. For example, to import everything but
104 'fail', you'd do:
105 use Test::More tests => 23, import => ['!fail'];
107 Alternatively, you can use the "plan()" function. Useful for when you
109 have to calculate the number of tests.
110 use Test::More;
112 plan tests => keys %Stuff * 3;
113 or for deciding between running the tests at all:
115 use Test::More;
117 if( $^O eq 'MacOS' ) {
118 plan skip_all => 'Test irrelevant on MacOS';
119 }
120 else {
121 plan tests => 42;
122 }
123 done_testing
125 done_testing();
126 done_testing($number_of_tests);
127 If you don't know how many tests you're going to run, you can issue
129 the plan when you're done running tests.
130 $number_of_tests is the same as "plan()", it's the number of tests
132 you expected to run. You can omit this, in which case the number
133 of tests you ran doesn't matter, just the fact that your tests ran
134 to conclusion.
135 This is safer than and replaces the "no_plan" plan.
137 Note: You must never put "done_testing()" inside an "END { ... }"
139 block. The plan is there to ensure your test does not exit before
140 testing has completed. If you use an END block you completely
141 bypass this protection.
142 Test names
144 By convention, each test is assigned a number in order. This is
145 largely done automatically for you. However, it's often very useful to
146 assign a name to each test. Which would you rather see:
147 ok 4
149 not ok 5
150 ok 6
151 or
153 ok 4 - basic multi-variable
155 not ok 5 - simple exponential
156 ok 6 - force == mass * acceleration
157 The later gives you some idea of what failed. It also makes it easier
159 to find the test in your script, simply search for "simple
160 exponential".
161 All test functions take a name argument. It's optional, but highly
163 suggested that you use it.
164 I'm ok, you're not ok.
166 The basic purpose of this module is to print out either "ok #" or "not
167 ok #" depending on if a given test succeeded or failed. Everything
168 else is just gravy.
169 All of the following print "ok" or "not ok" depending on if the test
171 succeeded or failed. They all also return true or false, respectively.
172 ok
174 ok($got eq $expected, $test_name);
175 This simply evaluates any expression ("$got eq $expected" is just a
177 simple example) and uses that to determine if the test succeeded or
178 failed. A true expression passes, a false one fails. Very simple.
179 For example:
181 ok( $exp{9} == 81, 'simple exponential' );
183 ok( Film->can('db_Main'), 'set_db()' );
184 ok( $p->tests == 4, 'saw tests' );
185 ok( !grep(!defined $_, @items), 'all items defined' );
186 (Mnemonic: "This is ok.")
188 $test_name is a very short description of the test that will be
190 printed out. It makes it very easy to find a test in your script
191 when it fails and gives others an idea of your intentions.
192 $test_name is optional, but we very strongly encourage its use.
193 Should an "ok()" fail, it will produce some diagnostics:
195 not ok 18 - sufficient mucus
197 # Failed test 'sufficient mucus'
198 # in foo.t at line 42.
199 This is the same as Test::Simple's "ok()" routine.
201 is
203 isnt
204 is ( $got, $expected, $test_name );
205 isnt( $got, $expected, $test_name );
206 Similar to "ok()", "is()" and "isnt()" compare their two arguments
208 with "eq" and "ne" respectively and use the result of that to
209 determine if the test succeeded or failed. So these:
210 # Is the ultimate answer 42?
212 is( ultimate_answer(), 42, "Meaning of Life" );
213 # $foo isn't empty
215 isnt( $foo, '', "Got some foo" );
216 are similar to these:
218 ok( ultimate_answer() eq 42, "Meaning of Life" );
220 ok( $foo ne '', "Got some foo" );
221 "undef" will only ever match "undef". So you can test a value
223 against "undef" like this:
224 is($not_defined, undef, "undefined as expected");
226 (Mnemonic: "This is that." "This isn't that.")
228 So why use these? They produce better diagnostics on failure.
230 "ok()" cannot know what you are testing for (beyond the name), but
231 "is()" and "isnt()" know what the test was and why it failed. For
232 example this test:
233 my $foo = 'waffle'; my $bar = 'yarblokos';
235 is( $foo, $bar, 'Is foo the same as bar?' );
236 Will produce something like this:
238 not ok 17 - Is foo the same as bar?
240 # Failed test 'Is foo the same as bar?'
241 # in foo.t at line 139.
242 # got: 'waffle'
243 # expected: 'yarblokos'
244 So you can figure out what went wrong without rerunning the test.
246 You are encouraged to use "is()" and "isnt()" over "ok()" where
248 possible, however do not be tempted to use them to find out if
249 something is true or false!
250 # XXX BAD!
252 is( exists $brooklyn{tree}, 1, 'A tree grows in Brooklyn' );
253 This does not check if "exists $brooklyn{tree}" is true, it checks
255 if it returns 1. Very different. Similar caveats exist for false
256 and 0. In these cases, use "ok()".
257 ok( exists $brooklyn{tree}, 'A tree grows in Brooklyn' );
259 A simple call to "isnt()" usually does not provide a strong test
261 but there are cases when you cannot say much more about a value
262 than that it is different from some other value:
263 new_ok $obj, "Foo";
265 my $clone = $obj->clone;
267 isa_ok $obj, "Foo", "Foo->clone";
268 isnt $obj, $clone, "clone() produces a different object";
270 For those grammatical pedants out there, there's an "isn't()"
272 function which is an alias of "isnt()".
273 like
275 like( $got, qr/expected/, $test_name );
276 Similar to "ok()", "like()" matches $got against the regex
278 "qr/expected/".
279 So this:
281 like($got, qr/expected/, 'this is like that');
283 is similar to:
285 ok( $got =~ m/expected/, 'this is like that');
287 (Mnemonic "This is like that".)
289 The second argument is a regular expression. It may be given as a
291 regex reference (i.e. "qr//") or (for better compatibility with
292 older perls) as a string that looks like a regex (alternative
293 delimiters are currently not supported):
294 like( $got, '/expected/', 'this is like that' );
296 Regex options may be placed on the end ('/expected/i').
298 Its advantages over "ok()" are similar to that of "is()" and
300 "isnt()". Better diagnostics on failure.
301 unlike
303 unlike( $got, qr/expected/, $test_name );
304 Works exactly as "like()", only it checks if $got does not match
306 the given pattern.
307 cmp_ok
309 cmp_ok( $got, $op, $expected, $test_name );
310 Halfway between "ok()" and "is()" lies "cmp_ok()". This allows you
312 to compare two arguments using any binary perl operator. The test
313 passes if the comparison is true and fails otherwise.
314 # ok( $got eq $expected );
316 cmp_ok( $got, 'eq', $expected, 'this eq that' );
317 # ok( $got == $expected );
319 cmp_ok( $got, '==', $expected, 'this == that' );
320 # ok( $got && $expected );
322 cmp_ok( $got, '&&', $expected, 'this && that' );
323 ...etc...
324 Its advantage over "ok()" is when the test fails you'll know what
326 $got and $expected were:
327 not ok 1
329 # Failed test in foo.t at line 12.
330 # '23'
331 # &&
332 # undef
333 It's also useful in those cases where you are comparing numbers and
335 "is()"'s use of "eq" will interfere:
336 cmp_ok( $big_hairy_number, '==', $another_big_hairy_number );
338 It's especially useful when comparing greater-than or smaller-than
340 relation between values:
341 cmp_ok( $some_value, '<=', $upper_limit );
343 can_ok
345 can_ok($module, @methods);
346 can_ok($object, @methods);
347 Checks to make sure the $module or $object can do these @methods
349 (works with functions, too).
350 can_ok('Foo', qw(this that whatever));
352 is almost exactly like saying:
354 ok( Foo->can('this') &&
356 Foo->can('that') &&
357 Foo->can('whatever')
358 );
359 only without all the typing and with a better interface. Handy for
361 quickly testing an interface.
362 No matter how many @methods you check, a single "can_ok()" call
364 counts as one test. If you desire otherwise, use:
365 foreach my $meth (@methods) {
367 can_ok('Foo', $meth);
368 }
369 isa_ok
371 isa_ok($object, $class, $object_name);
372 isa_ok($subclass, $class, $object_name);
373 isa_ok($ref, $type, $ref_name);
374 Checks to see if the given "$object->isa($class)". Also checks to
376 make sure the object was defined in the first place. Handy for
377 this sort of thing:
378 my $obj = Some::Module->new;
380 isa_ok( $obj, 'Some::Module' );
381 where you'd otherwise have to write
383 my $obj = Some::Module->new;
385 ok( defined $obj && $obj->isa('Some::Module') );
386 to safeguard against your test script blowing up.
388 You can also test a class, to make sure that it has the right
390 ancestor:
391 isa_ok( 'Vole', 'Rodent' );
393 It works on references, too:
395 isa_ok( $array_ref, 'ARRAY' );
397 The diagnostics of this test normally just refer to 'the object'.
399 If you'd like them to be more specific, you can supply an
400 $object_name (for example 'Test customer').
401 new_ok
403 my $obj = new_ok( $class );
404 my $obj = new_ok( $class => \@args );
405 my $obj = new_ok( $class => \@args, $object_name );
406 A convenience function which combines creating an object and
408 calling "isa_ok()" on that object.
409 It is basically equivalent to:
411 my $obj = $class->new(@args);
413 isa_ok $obj, $class, $object_name;
414 If @args is not given, an empty list will be used.
416 This function only works on "new()" and it assumes "new()" will
418 return just a single object which isa $class.
419 subtest
421 subtest $name => \&code, @args;
422 "subtest()" runs the &code as its own little test with its own plan
424 and its own result. The main test counts this as a single test
425 using the result of the whole subtest to determine if its ok or not
426 ok.
427 For example...
429 use Test::More tests => 3;
431 pass("First test");
433 subtest 'An example subtest' => sub {
435 plan tests => 2;
436 pass("This is a subtest");
438 pass("So is this");
439 };
440 pass("Third test");
442 This would produce.
444 1..3
446 ok 1 - First test
447 # Subtest: An example subtest
448 1..2
449 ok 1 - This is a subtest
450 ok 2 - So is this
451 ok 2 - An example subtest
452 ok 3 - Third test
453 A subtest may call "skip_all". No tests will be run, but the
455 subtest is considered a skip.
456 subtest 'skippy' => sub {
458 plan skip_all => 'cuz I said so';
459 pass('this test will never be run');
460 };
461 Returns true if the subtest passed, false otherwise.
463 Due to how subtests work, you may omit a plan if you desire. This
465 adds an implicit "done_testing()" to the end of your subtest. The
466 following two subtests are equivalent:
467 subtest 'subtest with implicit done_testing()', sub {
469 ok 1, 'subtests with an implicit done testing should work';
470 ok 1, '... and support more than one test';
471 ok 1, '... no matter how many tests are run';
472 };
473 subtest 'subtest with explicit done_testing()', sub {
475 ok 1, 'subtests with an explicit done testing should work';
476 ok 1, '... and support more than one test';
477 ok 1, '... no matter how many tests are run';
478 done_testing();
479 };
480 Extra arguments given to "subtest" are passed to the callback. For
482 example:
483 sub my_subtest {
485 my $range = shift;
486 ...
487 }
488 for my $range (1, 10, 100, 1000) {
490 subtest "testing range $range", \&my_subtest, $range;
491 }
492 pass
494 fail
495 pass($test_name);
496 fail($test_name);
497 Sometimes you just want to say that the tests have passed. Usually
499 the case is you've got some complicated condition that is difficult
500 to wedge into an "ok()". In this case, you can simply use "pass()"
501 (to declare the test ok) or fail (for not ok). They are synonyms
502 for ok(1) and ok(0).
503 Use these very, very, very sparingly.
505 Module tests
507 Sometimes you want to test if a module, or a list of modules, can
508 successfully load. For example, you'll often want a first test which
509 simply loads all the modules in the distribution to make sure they work
510 before going on to do more complicated testing.
511 For such purposes we have "use_ok" and "require_ok".
513 require_ok
515 require_ok($module);
516 require_ok($file);
517 Tries to "require" the given $module or $file. If it loads
519 successfully, the test will pass. Otherwise it fails and displays
520 the load error.
521 "require_ok" will guess whether the input is a module name or a
523 filename.
524 No exception will be thrown if the load fails.
526 # require Some::Module
528 require_ok "Some::Module";
529 # require "Some/File.pl";
531 require_ok "Some/File.pl";
532 # stop testing if any of your modules will not load
534 for my $module (@module) {
535 require_ok $module or BAIL_OUT "Can't load $module";
536 }
537 use_ok
539 BEGIN { use_ok($module); }
540 BEGIN { use_ok($module, @imports); }
541 Like "require_ok", but it will "use" the $module in question and
543 only loads modules, not files.
544 If you just want to test a module can be loaded, use "require_ok".
546 If you just want to load a module in a test, we recommend simply
548 using "use" directly. It will cause the test to stop.
549 It's recommended that you run "use_ok()" inside a BEGIN block so
551 its functions are exported at compile-time and prototypes are
552 properly honored.
553 If @imports are given, they are passed through to the use. So
555 this:
556 BEGIN { use_ok('Some::Module', qw(foo bar)) }
558 is like doing this:
560 use Some::Module qw(foo bar);
562 Version numbers can be checked like so:
564 # Just like "use Some::Module 1.02"
566 BEGIN { use_ok('Some::Module', 1.02) }
567 Don't try to do this:
569 BEGIN {
571 use_ok('Some::Module');
572 ...some code that depends on the use...
574 ...happening at compile time...
575 }
576 because the notion of "compile-time" is relative. Instead, you
578 want:
579 BEGIN { use_ok('Some::Module') }
581 BEGIN { ...some code that depends on the use... }
582 If you want the equivalent of "use Foo ()", use a module but not
584 import anything, use "require_ok".
585 BEGIN { require_ok "Foo" }
587 Complex data structures
589 Not everything is a simple eq check or regex. There are times you need
590 to see if two data structures are equivalent. For these instances
591 Test::More provides a handful of useful functions.
592 NOTE I'm not quite sure what will happen with filehandles.
594 is_deeply
596 is_deeply( $got, $expected, $test_name );
597 Similar to "is()", except that if $got and $expected are
599 references, it does a deep comparison walking each data structure
600 to see if they are equivalent. If the two structures are
601 different, it will display the place where they start differing.
602 "is_deeply()" compares the dereferenced values of references, the
604 references themselves (except for their type) are ignored. This
605 means aspects such as blessing and ties are not considered
606 "different".
607 "is_deeply()" currently has very limited handling of function
609 reference and globs. It merely checks if they have the same
610 referent. This may improve in the future.
611 Test::Differences and Test::Deep provide more in-depth
613 functionality along these lines.
614 NOTE is_deeply() has limitations when it comes to comparing strings
616 and refs:
617 my $path = path('.');
619 my $hash = {};
620 is_deeply( $path, "$path" ); # ok
621 is_deeply( $hash, "$hash" ); # fail
622 This happens because is_deeply will unoverload all arguments
624 unconditionally. It is probably best not to use is_deeply with
625 overloading. For legacy reasons this is not likely to ever be
626 fixed. If you would like a much better tool for this you should see
627 Test2::Suite Specifically Test2::Tools::Compare has an "is()"
628 function that works like "is_deeply" with many improvements.
629 Diagnostics
631 If you pick the right test function, you'll usually get a good idea of
632 what went wrong when it failed. But sometimes it doesn't work out that
633 way. So here we have ways for you to write your own diagnostic
634 messages which are safer than just "print STDERR".
635 diag
637 diag(@diagnostic_message);
638 Prints a diagnostic message which is guaranteed not to interfere
640 with test output. Like "print" @diagnostic_message is simply
641 concatenated together.
642 Returns false, so as to preserve failure.
644 Handy for this sort of thing:
646 ok( grep(/foo/, @users), "There's a foo user" ) or
648 diag("Since there's no foo, check that /etc/bar is set up right");
649 which would produce:
651 not ok 42 - There's a foo user
653 # Failed test 'There's a foo user'
654 # in foo.t at line 52.
655 # Since there's no foo, check that /etc/bar is set up right.
656 You might remember "ok() or diag()" with the mnemonic "open() or
658 die()".
659 NOTE The exact formatting of the diagnostic output is still
661 changing, but it is guaranteed that whatever you throw at it won't
662 interfere with the test.
663 note
665 note(@diagnostic_message);
666 Like "diag()", except the message will not be seen when the test is
668 run in a harness. It will only be visible in the verbose TAP
669 stream.
670 Handy for putting in notes which might be useful for debugging, but
672 don't indicate a problem.
673 note("Tempfile is $tempfile");
675 explain
677 my @dump = explain @diagnostic_message;
678 Will dump the contents of any references in a human readable
680 format. Usually you want to pass this into "note" or "diag".
681 Handy for things like...
683 is_deeply($have, $want) || diag explain $have;
685 or
687 note explain \%args;
689 Some::Class->method(%args);
690 Conditional tests
692 Sometimes running a test under certain conditions will cause the test
693 script to die. A certain function or method isn't implemented (such as
694 "fork()" on MacOS), some resource isn't available (like a net
695 connection) or a module isn't available. In these cases it's necessary
696 to skip tests, or declare that they are supposed to fail but will work
697 in the future (a todo test).
698 For more details on the mechanics of skip and todo tests see
700 Test::Harness.
701 The way Test::More handles this is with a named block. Basically, a
703 block of tests which can be skipped over or made todo. It's best if I
704 just show you...
705 SKIP: BLOCK
707 SKIP: {
708 skip $why, $how_many if $condition;
709 ...normal testing code goes here...
711 }
712 This declares a block of tests that might be skipped, $how_many
714 tests there are, $why and under what $condition to skip them. An
715 example is the easiest way to illustrate:
716 SKIP: {
718 eval { require HTML::Lint };
719 skip "HTML::Lint not installed", 2 if $@;
721 my $lint = new HTML::Lint;
723 isa_ok( $lint, "HTML::Lint" );
724 $lint->parse( $html );
726 is( $lint->errors, 0, "No errors found in HTML" );
727 }
728 If the user does not have HTML::Lint installed, the whole block of
730 code won't be run at all. Test::More will output special ok's
731 which Test::Harness interprets as skipped, but passing, tests.
732 It's important that $how_many accurately reflects the number of
734 tests in the SKIP block so the # of tests run will match up with
735 your plan. If your plan is "no_plan" $how_many is optional and
736 will default to 1.
737 It's perfectly safe to nest SKIP blocks. Each SKIP block must have
739 the label "SKIP", or Test::More can't work its magic.
740 You don't skip tests which are failing because there's a bug in
742 your program, or for which you don't yet have code written. For
743 that you use TODO. Read on.
744 TODO: BLOCK
746 TODO: {
747 local $TODO = $why if $condition;
748 ...normal testing code goes here...
750 }
751 Declares a block of tests you expect to fail and $why. Perhaps
753 it's because you haven't fixed a bug or haven't finished a new
754 feature:
755 TODO: {
757 local $TODO = "URI::Geller not finished";
758 my $card = "Eight of clubs";
760 is( URI::Geller->your_card, $card, 'Is THIS your card?' );
761 my $spoon;
763 URI::Geller->bend_spoon;
764 is( $spoon, 'bent', "Spoon bending, that's original" );
765 }
766 With a todo block, the tests inside are expected to fail.
768 Test::More will run the tests normally, but print out special flags
769 indicating they are "todo". Test::Harness will interpret failures
770 as being ok. Should anything succeed, it will report it as an
771 unexpected success. You then know the thing you had todo is done
772 and can remove the TODO flag.
773 The nice part about todo tests, as opposed to simply commenting out
775 a block of tests, is it's like having a programmatic todo list.
776 You know how much work is left to be done, you're aware of what
777 bugs there are, and you'll know immediately when they're fixed.
778 Once a todo test starts succeeding, simply move it outside the
780 block. When the block is empty, delete it.
781 todo_skip
783 TODO: {
784 todo_skip $why, $how_many if $condition;
785 ...normal testing code...
787 }
788 With todo tests, it's best to have the tests actually run. That
790 way you'll know when they start passing. Sometimes this isn't
791 possible. Often a failing test will cause the whole program to die
792 or hang, even inside an "eval BLOCK" with and using "alarm". In
793 these extreme cases you have no choice but to skip over the broken
794 tests entirely.
795 The syntax and behavior is similar to a "SKIP: BLOCK" except the
797 tests will be marked as failing but todo. Test::Harness will
798 interpret them as passing.
799 When do I use SKIP vs. TODO?
801 If it's something the user might not be able to do, use SKIP. This
802 includes optional modules that aren't installed, running under an
803 OS that doesn't have some feature (like "fork()" or symlinks), or
804 maybe you need an Internet connection and one isn't available.
805 If it's something the programmer hasn't done yet, use TODO. This
807 is for any code you haven't written yet, or bugs you have yet to
808 fix, but want to put tests in your testing script (always a good
809 idea).
810 Test control
812 BAIL_OUT
813 BAIL_OUT($reason);
814 Indicates to the harness that things are going so badly all testing
816 should terminate. This includes the running of any additional test
817 scripts.
818 This is typically used when testing cannot continue such as a
820 critical module failing to compile or a necessary external utility
821 not being available such as a database connection failing.
822 The test will exit with 255.
824 For even better control look at Test::Most.
826 Discouraged comparison functions
828 The use of the following functions is discouraged as they are not
829 actually testing functions and produce no diagnostics to help figure
830 out what went wrong. They were written before "is_deeply()" existed
831 because I couldn't figure out how to display a useful diff of two
832 arbitrary data structures.
833 These functions are usually used inside an "ok()".
835 ok( eq_array(\@got, \@expected) );
837 "is_deeply()" can do that better and with diagnostics.
839 is_deeply( \@got, \@expected );
841 They may be deprecated in future versions.
843 eq_array
845 my $is_eq = eq_array(\@got, \@expected);
846 Checks if two arrays are equivalent. This is a deep check, so
848 multi-level structures are handled correctly.
849 eq_hash
851 my $is_eq = eq_hash(\%got, \%expected);
852 Determines if the two hashes contain the same keys and values.
854 This is a deep check.
855 eq_set
857 my $is_eq = eq_set(\@got, \@expected);
858 Similar to "eq_array()", except the order of the elements is not
860 important. This is a deep check, but the irrelevancy of order only
861 applies to the top level.
862 ok( eq_set(\@got, \@expected) );
864 Is better written:
866 is_deeply( [sort @got], [sort @expected] );
868 NOTE By historical accident, this is not a true set comparison.
870 While the order of elements does not matter, duplicate elements do.
871 NOTE "eq_set()" does not know how to deal with references at the
873 top level. The following is an example of a comparison which might
874 not work:
875 eq_set([\1, \2], [\2, \1]);
877 Test::Deep contains much better set comparison functions.
879 Extending and Embedding Test::More
881 Sometimes the Test::More interface isn't quite enough. Fortunately,
882 Test::More is built on top of Test::Builder which provides a single,
883 unified backend for any test library to use. This means two test
884 libraries which both use <Test::Builder> can be used together in the
885 same program>.
886 If you simply want to do a little tweaking of how the tests behave, you
888 can access the underlying Test::Builder object like so:
889 builder
891 my $test_builder = Test::More->builder;
892 Returns the Test::Builder object underlying Test::More for you to
894 play with.
895
897 If all your tests passed, Test::Builder will exit with zero (which is
898 normal). If anything failed it will exit with how many failed. If you
899 run less (or more) tests than you planned, the missing (or extras) will
900 be considered failures. If no tests were ever run Test::Builder will
901 throw a warning and exit with 255. If the test died, even after having
902 successfully completed all its tests, it will still be considered a
903 failure and will exit with 255.
904 So the exit codes are...
906 0 all tests successful
908 255 test died or all passed but wrong # of tests run
909 any other number how many failed (including missing or extras)
910 If you fail more than 254 tests, it will be reported as 254.
912 NOTE This behavior may go away in future versions.
914
916 Test::More works with Perls as old as 5.8.1.
917 Thread support is not very reliable before 5.10.1, but that's because
919 threads are not very reliable before 5.10.1.
920 Although Test::More has been a core module in versions of Perl since
922 5.6.2, Test::More has evolved since then, and not all of the features
923 you're used to will be present in the shipped version of Test::More. If
924 you are writing a module, don't forget to indicate in your package
925 metadata the minimum version of Test::More that you require. For
926 instance, if you want to use "done_testing()" but want your test script
927 to run on Perl 5.10.0, you will need to explicitly require Test::More >
928 0.88.
929 Key feature milestones include:
931 subtests
933 Subtests were released in Test::More 0.94, which came with Perl
934 5.12.0. Subtests did not implicitly call "done_testing()" until
935 0.96; the first Perl with that fix was Perl 5.14.0 with 0.98.
936 "done_testing()"
938 This was released in Test::More 0.88 and first shipped with Perl in
939 5.10.1 as part of Test::More 0.92.
940 "cmp_ok()"
942 Although "cmp_ok()" was introduced in 0.40, 0.86 fixed an important
943 bug to make it safe for overloaded objects; the fixed first shipped
944 with Perl in 5.10.1 as part of Test::More 0.92.
945 "new_ok()" "note()" and "explain()"
947 These were was released in Test::More 0.82, and first shipped with
948 Perl in 5.10.1 as part of Test::More 0.92.
949 There is a full version history in the Changes file, and the Test::More
951 versions included as core can be found using Module::CoreList:
952 $ corelist -a Test::More
954
956 utf8 / "Wide character in print"
957 If you use utf8 or other non-ASCII characters with Test::More you
958 might get a "Wide character in print" warning. Using "binmode
959 STDOUT, ":utf8"" will not fix it. Test::Builder (which powers
960 Test::More) duplicates STDOUT and STDERR. So any changes to them,
961 including changing their output disciplines, will not be seem by
962 Test::More.
963 One work around is to apply encodings to STDOUT and STDERR as early
965 as possible and before Test::More (or any other Test module) loads.
966 use open ':std', ':encoding(utf8)';
968 use Test::More;
969 A more direct work around is to change the filehandles used by
971 Test::Builder.
972 my $builder = Test::More->builder;
974 binmode $builder->output, ":encoding(utf8)";
975 binmode $builder->failure_output, ":encoding(utf8)";
976 binmode $builder->todo_output, ":encoding(utf8)";
977 Overloaded objects
979 String overloaded objects are compared as strings (or in
980 "cmp_ok()"'s case, strings or numbers as appropriate to the
981 comparison op). This prevents Test::More from piercing an object's
982 interface allowing better blackbox testing. So if a function
983 starts returning overloaded objects instead of bare strings your
984 tests won't notice the difference. This is good.
985 However, it does mean that functions like "is_deeply()" cannot be
987 used to test the internals of string overloaded objects. In this
988 case I would suggest Test::Deep which contains more flexible
989 testing functions for complex data structures.
990 Threads
992 Test::More will only be aware of threads if "use threads" has been
993 done before Test::More is loaded. This is ok:
994 use threads;
996 use Test::More;
997 This may cause problems:
999 use Test::More
1001 use threads;
1002 5.8.1 and above are supported. Anything below that has too many
1004 bugs.
1005
1007 This is a case of convergent evolution with Joshua Pritikin's Test
1008 module. I was largely unaware of its existence when I'd first written
1009 my own "ok()" routines. This module exists because I can't figure out
1010 how to easily wedge test names into Test's interface (along with a few
1011 other problems).
1012 The goal here is to have a testing utility that's simple to learn,
1014 quick to use and difficult to trip yourself up with while still
1015 providing more flexibility than the existing Test.pm. As such, the
1016 names of the most common routines are kept tiny, special cases and
1017 magic side-effects are kept to a minimum. WYSIWYG.
1018
1020 ALTERNATIVES
1022 Test::Simple if all this confuses you and you just want to write some
1023 tests. You can upgrade to Test::More later (it's forward compatible).
1024 Test::Legacy tests written with Test.pm, the original testing module,
1026 do not play well with other testing libraries. Test::Legacy emulates
1027 the Test.pm interface and does play well with others.
1028 TESTING FRAMEWORKS
1030 Fennec The Fennec framework is a testers toolbox. It uses Test::Builder
1031 under the hood. It brings enhancements for forking, defining state, and
1032 mocking. Fennec enhances several modules to work better together than
1033 they would if you loaded them individually on your own.
1034 Fennec::Declare Provides enhanced (Devel::Declare) syntax for Fennec.
1036 ADDITIONAL LIBRARIES
1038 Test::Differences for more ways to test complex data structures. And
1039 it plays well with Test::More.
1040 Test::Class is like xUnit but more perlish.
1042 Test::Deep gives you more powerful complex data structure testing.
1044 Test::Inline shows the idea of embedded testing.
1046 Mock::Quick The ultimate mocking library. Easily spawn objects defined
1048 on the fly. Can also override, block, or reimplement packages as
1049 needed.
1050 Test::FixtureBuilder Quickly define fixture data for unit tests.
1052 OTHER COMPONENTS
1054 Test::Harness is the test runner and output interpreter for Perl. It's
1055 the thing that powers "make test" and where the "prove" utility comes
1056 from.
1057 BUNDLES
1059 Test::Most Most commonly needed test functions and features.
1060
1062 Michael G Schwern <schwern@pobox.com> with much inspiration from Joshua
1063 Pritikin's Test module and lots of help from Barrie Slaymaker, Tony
1064 Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa gang.
1065
1067 Chad Granum <exodist@cpan.org>
1068
1070 See https://github.com/Test-More/test-more/issues to report and view
1071 bugs.
1072
1074 The source code repository for Test::More can be found at
1075 http://github.com/Test-More/test-more/.
1076
1078 Copyright 2001-2008 by Michael G Schwern <schwern@pobox.com>.
1079 This program is free software; you can redistribute it and/or modify it
1081 under the same terms as Perl itself.
1082 See http://www.perl.com/perl/misc/Artistic.html
1084perl v5.26.3 2018-03-30 Test::More(3)