1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Test::More 3"
132 .TH Test::More 3 "2009-09-02" "perl v5.8.7" "User Contributed Perl Documentation"
134 Test::More \- yet another framework for writing test scripts
136 .IX Header "SYNOPSIS"
138 \& use Test::More tests => 23;
140 \& use Test::More skip_all => $reason;
142 \& use Test::More; # see done_testing()
146 \& BEGIN { use_ok( 'Some::Module' ); }
147 \& require_ok( 'Some::Module' );
151 \& # Various ways to say "ok"
152 \& ok($got eq $expected, $test_name);
156 \& is ($got, $expected, $test_name);
157 \& isnt($got, $expected, $test_name);
161 \& # Rather than print STDERR "# here's what went wrong\en"
162 \& diag("here's what went wrong");
166 \& like ($got, qr/expected/, $test_name);
167 \& unlike($got, qr/expected/, $test_name);
171 \& cmp_ok($got, '==', $expected, $test_name);
175 \& is_deeply($got_complex_structure, $expected_complex_structure, $test_name);
180 \& skip $why, $how_many unless $have_some_feature;
184 \& ok( foo(), $test_name );
185 \& is( foo(42), 23, $test_name );
191 \& local $TODO = $why;
195 \& ok( foo(), $test_name );
196 \& is( foo(42), 23, $test_name );
201 \& can_ok($module, @methods);
202 \& isa_ok($object, $class);
215 \& # UNIMPLEMENTED!!!
216 \& my @status = Test::More::status;
219 .IX Header "DESCRIPTION"
220 \&\fB\s-1STOP\s0!\fR If you're just getting started writing tests, have a look at
221 Test::Simple first. This is a drop in replacement for Test::Simple
222 which you can switch to once you get the hang of basic testing.
224 The purpose of this module is to provide a wide range of testing
225 utilities. Various ways to say \*(L"ok\*(R" with better diagnostics,
226 facilities to skip tests, test future features and compare complicated
227 data structures. While you can do almost anything with a simple
228 \&\f(CW\*(C`ok()\*(C'\fR function, it doesn't provide good diagnostic output.
229 .Sh "I love it when a plan comes together"
230 .IX Subsection "I love it when a plan comes together"
231 Before anything else, you need a testing plan. This basically declares
232 how many tests your script is going to run to protect against premature
235 The preferred way to do this is to declare a plan when you \f(CW\*(C`use Test::More\*(C'\fR.
238 \& use Test::More tests => 23;
241 There are cases when you will not know beforehand how many tests your
242 script is going to run. In this case, you can declare your tests at
250 \& ... run your tests ...
254 \& done_testing( $number_of_tests_run );
257 Sometimes you really don't know how many tests were run, or it's too
258 difficult to calculate. In which case you can leave off
259 \&\f(CW$number_of_tests_run\fR.
261 In some cases, you'll want to completely skip an entire testing script.
264 \& use Test::More skip_all => $skip_reason;
267 Your script will declare a skip with the reason why you skipped and
268 exit immediately with a zero (success). See Test::Harness for
271 If you want to control what functions Test::More will export, you
272 have to use the 'import' option. For example, to import everything
273 but 'fail', you'd do:
276 \& use Test::More tests => 23, import => ['!fail'];
279 Alternatively, you can use the \fIplan()\fR function. Useful for when you
280 have to calculate the number of tests.
284 \& plan tests => keys %Stuff * 3;
287 or for deciding between running the tests at all:
291 \& if( $^O eq 'MacOS' ) {
292 \& plan skip_all => 'Test irrelevant on MacOS';
298 .IP "\fBdone_testing\fR" 4
299 .IX Item "done_testing"
302 \& done_testing($number_of_tests);
305 If you don't know how many tests you're going to run, you can issue
306 the plan when you're done running tests.
308 $number_of_tests is the same as \fIplan()\fR, it's the number of tests you
309 expected to run. You can omit this, in which case the number of tests
310 you ran doesn't matter, just the fact that your tests ran to
313 This is safer than and replaces the \*(L"no_plan\*(R" plan.
315 .IX Subsection "Test names"
316 By convention, each test is assigned a number in order. This is
317 largely done automatically for you. However, it's often very useful to
318 assign a name to each test. Which would you rather see:
329 \& ok 4 \- basic multi\-variable
330 \& not ok 5 \- simple exponential
331 \& ok 6 \- force == mass * acceleration
334 The later gives you some idea of what failed. It also makes it easier
335 to find the test in your script, simply search for \*(L"simple
338 All test functions take a name argument. It's optional, but highly
339 suggested that you use it.
340 .Sh "I'm ok, you're not ok."
341 .IX Subsection "I'm ok, you're not ok."
342 The basic purpose of this module is to print out either \*(L"ok #\*(R" or \*(L"not
343 ok #\*(R" depending on if a given test succeeded or failed. Everything
346 All of the following print \*(L"ok\*(R" or \*(L"not ok\*(R" depending on if the test
347 succeeded or failed. They all also return true or false,
352 \& ok($got eq $expected, $test_name);
355 This simply evaluates any expression (\f(CW\*(C`$got eq $expected\*(C'\fR is just a
356 simple example) and uses that to determine if the test succeeded or
357 failed. A true expression passes, a false one fails. Very simple.
362 \& ok( $exp{9} == 81, 'simple exponential' );
363 \& ok( Film\->can('db_Main'), 'set_db()' );
364 \& ok( $p\->tests == 4, 'saw tests' );
365 \& ok( !grep !defined $_, @items, 'items populated' );
368 (Mnemonic: \*(L"This is ok.\*(R")
370 $test_name is a very short description of the test that will be printed
371 out. It makes it very easy to find a test in your script when it fails
372 and gives others an idea of your intentions. \f(CW$test_name\fR is optional,
373 but we \fBvery\fR strongly encourage its use.
375 Should an \fIok()\fR fail, it will produce some diagnostics:
378 \& not ok 18 \- sufficient mucus
379 \& # Failed test 'sufficient mucus'
380 \& # in foo.t at line 42.
383 This is the same as Test::Simple's \fIok()\fR routine.
391 \& is ( $got, $expected, $test_name );
392 \& isnt( $got, $expected, $test_name );
395 Similar to \fIok()\fR, \fIis()\fR and \fIisnt()\fR compare their two arguments
396 with \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`ne\*(C'\fR respectively and use the result of that to
397 determine if the test succeeded or failed. So these:
400 \& # Is the ultimate answer 42?
401 \& is( ultimate_answer(), 42, "Meaning of Life" );
405 \& # $foo isn't empty
406 \& isnt( $foo, '', "Got some foo" );
409 are similar to these:
412 \& ok( ultimate_answer() eq 42, "Meaning of Life" );
413 \& ok( $foo ne '', "Got some foo" );
416 (Mnemonic: \*(L"This is that.\*(R" \*(L"This isn't that.\*(R")
418 So why use these? They produce better diagnostics on failure. \fIok()\fR
419 cannot know what you are testing for (beyond the name), but \fIis()\fR and
420 \&\fIisnt()\fR know what the test was and why it failed. For example this
424 \& my $foo = 'waffle'; my $bar = 'yarblokos';
425 \& is( $foo, $bar, 'Is foo the same as bar?' );
428 Will produce something like this:
431 \& not ok 17 \- Is foo the same as bar?
432 \& # Failed test 'Is foo the same as bar?'
433 \& # in foo.t at line 139.
435 \& # expected: 'yarblokos'
438 So you can figure out what went wrong without rerunning the test.
440 You are encouraged to use \fIis()\fR and \fIisnt()\fR over \fIok()\fR where possible,
441 however do not be tempted to use them to find out if something is
446 \& is( exists $brooklyn{tree}, 1, 'A tree grows in Brooklyn' );
449 This does not check if \f(CW\*(C`exists $brooklyn{tree}\*(C'\fR is true, it checks if
450 it returns 1. Very different. Similar caveats exist for false and 0.
451 In these cases, use \fIok()\fR.
454 \& ok( exists $brooklyn{tree}, 'A tree grows in Brooklyn' );
457 A simple call to \fIisnt()\fR usually does not provide a strong test but there
458 are cases when you cannot say much more about a value than that it is
459 different from some other value:
462 \& new_ok $obj, "Foo";
466 \& my $clone = $obj\->clone;
467 \& isa_ok $obj, "Foo", "Foo\->clone";
471 \& isnt $obj, $clone, "clone() produces a different object";
474 For those grammatical pedants out there, there's an \f(CW\*(C`isn't()\*(C'\fR
475 function which is an alias of \fIisnt()\fR.
479 \& like( $got, qr/expected/, $test_name );
482 Similar to \fIok()\fR, \fIlike()\fR matches \f(CW$got\fR against the regex \f(CW\*(C`qr/expected/\*(C'\fR.
487 \& like($got, qr/expected/, 'this is like that');
493 \& ok( $got =~ /expected/, 'this is like that');
496 (Mnemonic \*(L"This is like that\*(R".)
498 The second argument is a regular expression. It may be given as a
499 regex reference (i.e. \f(CW\*(C`qr//\*(C'\fR) or (for better compatibility with older
500 perls) as a string that looks like a regex (alternative delimiters are
501 currently not supported):
504 \& like( $got, '/expected/', 'this is like that' );
507 Regex options may be placed on the end (\f(CW'/expected/i'\fR).
509 Its advantages over \fIok()\fR are similar to that of \fIis()\fR and \fIisnt()\fR. Better
510 diagnostics on failure.
514 \& unlike( $got, qr/expected/, $test_name );
517 Works exactly as \fIlike()\fR, only it checks if \f(CW$got\fR \fBdoes not\fR match the
522 \& cmp_ok( $got, $op, $expected, $test_name );
525 Halfway between \fIok()\fR and \fIis()\fR lies \fIcmp_ok()\fR. This allows you to
526 compare two arguments using any binary perl operator.
529 \& # ok( $got eq $expected );
530 \& cmp_ok( $got, 'eq', $expected, 'this eq that' );
534 \& # ok( $got == $expected );
535 \& cmp_ok( $got, '==', $expected, 'this == that' );
539 \& # ok( $got && $expected );
540 \& cmp_ok( $got, '&&', $expected, 'this && that' );
544 Its advantage over \fIok()\fR is when the test fails you'll know what \f(CW$got\fR
545 and \f(CW$expected\fR were:
549 \& # Failed test in foo.t at line 12.
555 It's also useful in those cases where you are comparing numbers and
556 \&\fIis()\fR's use of \f(CW\*(C`eq\*(C'\fR will interfere:
559 \& cmp_ok( $big_hairy_number, '==', $another_big_hairy_number );
562 It's especially useful when comparing greater-than or smaller-than
563 relation between values:
566 \& cmp_ok( $some_value, '<=', $upper_limit );
571 \& can_ok($module, @methods);
572 \& can_ok($object, @methods);
575 Checks to make sure the \f(CW$module\fR or \f(CW$object\fR can do these \f(CW@methods\fR
576 (works with functions, too).
579 \& can_ok('Foo', qw(this that whatever));
582 is almost exactly like saying:
585 \& ok( Foo\->can('this') &&
586 \& Foo\->can('that') &&
587 \& Foo\->can('whatever')
591 only without all the typing and with a better interface. Handy for
592 quickly testing an interface.
594 No matter how many \f(CW@methods\fR you check, a single \fIcan_ok()\fR call counts
595 as one test. If you desire otherwise, use:
598 \& foreach my $meth (@methods) {
599 \& can_ok('Foo', $meth);
605 \& isa_ok($object, $class, $object_name);
606 \& isa_ok($subclass, $class, $object_name);
607 \& isa_ok($ref, $type, $ref_name);
610 Checks to see if the given \f(CW\*(C`$object\->isa($class)\*(C'\fR. Also checks to make
611 sure the object was defined in the first place. Handy for this sort
615 \& my $obj = Some::Module\->new;
616 \& isa_ok( $obj, 'Some::Module' );
619 where you'd otherwise have to write
622 \& my $obj = Some::Module\->new;
623 \& ok( defined $obj && $obj\->isa('Some::Module') );
626 to safeguard against your test script blowing up.
628 You can also test a class, to make sure that it has the right ancestor:
631 \& isa_ok( 'Vole', 'Rodent' );
634 It works on references, too:
637 \& isa_ok( $array_ref, 'ARRAY' );
640 The diagnostics of this test normally just refer to 'the object'. If
641 you'd like them to be more specific, you can supply an \f(CW$object_name\fR
642 (for example 'Test customer').
646 \& my $obj = new_ok( $class );
647 \& my $obj = new_ok( $class => \e@args );
648 \& my $obj = new_ok( $class => \e@args, $object_name );
651 A convenience function which combines creating an object and calling
652 \&\fIisa_ok()\fR on that object.
654 It is basically equivalent to:
657 \& my $obj = $class\->new(@args);
658 \& isa_ok $obj, $class, $object_name;
661 If \f(CW@args\fR is not given, an empty list will be used.
663 This function only works on \fInew()\fR and it assumes \fInew()\fR will return
664 just a single object which isa \f(CW$class\fR.
665 .IP "\fBsubtest\fR" 4
668 \& subtest $name => \e&code;
671 \&\fIsubtest()\fR runs the &code as its own little test with its own plan and
672 its own result. The main test counts this as a single test using the
673 result of the whole subtest to determine if its ok or not ok.
678 \& use Test::More tests => 3;
682 \& pass("First test");
686 \& subtest 'An example subtest' => sub {
691 \& pass("This is a subtest");
692 \& pass("So is this");
697 \& pass("Third test");
704 \& ok 1 \- First test
706 \& ok 1 \- This is a subtest
707 \& ok 2 \- So is this
708 \& ok 2 \- An example subtest
709 \& ok 3 \- Third test
712 A subtest may call \*(L"skip_all\*(R". No tests will be run, but the subtest is
716 \& subtest 'skippy' => sub {
717 \& plan skip_all => 'cuz I said so';
718 \& pass('this test will never be run');
722 Returns true if the subtest passed, false otherwise.
734 Sometimes you just want to say that the tests have passed. Usually
735 the case is you've got some complicated condition that is difficult to
736 wedge into an \fIok()\fR. In this case, you can simply use \fIpass()\fR (to
737 declare the test ok) or fail (for not ok). They are synonyms for
738 \&\fIok\fR\|(1) and \fIok\fR\|(0).
740 Use these very, very, very sparingly.
742 .IX Subsection "Module tests"
743 You usually want to test if the module you're testing loads ok, rather
744 than just vomiting if its load fails. For such purposes we have
745 \&\f(CW\*(C`use_ok\*(C'\fR and \f(CW\*(C`require_ok\*(C'\fR.
749 \& BEGIN { use_ok($module); }
750 \& BEGIN { use_ok($module, @imports); }
753 These simply use the given \f(CW$module\fR and test to make sure the load
754 happened ok. It's recommended that you run \fIuse_ok()\fR inside a \s-1BEGIN\s0
755 block so its functions are exported at compile-time and prototypes are
758 If \f(CW@imports\fR are given, they are passed through to the use. So this:
761 \& BEGIN { use_ok('Some::Module', qw(foo bar)) }
767 \& use Some::Module qw(foo bar);
770 Version numbers can be checked like so:
773 \& # Just like "use Some::Module 1.02"
774 \& BEGIN { use_ok('Some::Module', 1.02) }
777 Don't try to do this:
781 \& use_ok('Some::Module');
785 \& ...some code that depends on the use...
786 \& ...happening at compile time...
790 because the notion of \*(L"compile\-time\*(R" is relative. Instead, you want:
793 \& BEGIN { use_ok('Some::Module') }
794 \& BEGIN { ...some code that depends on the use... }
796 .IP "\fBrequire_ok\fR" 4
797 .IX Item "require_ok"
799 \& require_ok($module);
800 \& require_ok($file);
803 Like \fIuse_ok()\fR, except it requires the \f(CW$module\fR or \f(CW$file\fR.
804 .Sh "Complex data structures"
805 .IX Subsection "Complex data structures"
806 Not everything is a simple eq check or regex. There are times you
807 need to see if two data structures are equivalent. For these
808 instances Test::More provides a handful of useful functions.
810 \&\fB\s-1NOTE\s0\fR I'm not quite sure what will happen with filehandles.
811 .IP "\fBis_deeply\fR" 4
814 \& is_deeply( $got, $expected, $test_name );
817 Similar to \fIis()\fR, except that if \f(CW$got\fR and \f(CW$expected\fR are references, it
818 does a deep comparison walking each data structure to see if they are
819 equivalent. If the two structures are different, it will display the
820 place where they start differing.
822 \&\fIis_deeply()\fR compares the dereferenced values of references, the
823 references themselves (except for their type) are ignored. This means
824 aspects such as blessing and ties are not considered \*(L"different\*(R".
826 \&\fIis_deeply()\fR currently has very limited handling of function reference
827 and globs. It merely checks if they have the same referent. This may
828 improve in the future.
830 Test::Differences and Test::Deep provide more in-depth functionality
833 .IX Subsection "Diagnostics"
834 If you pick the right test function, you'll usually get a good idea of
835 what went wrong when it failed. But sometimes it doesn't work out
836 that way. So here we have ways for you to write your own diagnostic
837 messages which are safer than just \f(CW\*(C`print STDERR\*(C'\fR.
841 \& diag(@diagnostic_message);
844 Prints a diagnostic message which is guaranteed not to interfere with
845 test output. Like \f(CW\*(C`print\*(C'\fR \f(CW@diagnostic_message\fR is simply concatenated
848 Returns false, so as to preserve failure.
850 Handy for this sort of thing:
853 \& ok( grep(/foo/, @users), "There's a foo user" ) or
854 \& diag("Since there's no foo, check that /etc/bar is set up right");
860 \& not ok 42 \- There's a foo user
861 \& # Failed test 'There's a foo user'
862 \& # in foo.t at line 52.
863 \& # Since there's no foo, check that /etc/bar is set up right.
866 You might remember \f(CW\*(C`ok() or diag()\*(C'\fR with the mnemonic \f(CW\*(C`open() or
869 \&\fB\s-1NOTE\s0\fR The exact formatting of the diagnostic output is still
870 changing, but it is guaranteed that whatever you throw at it it won't
871 interfere with the test.
875 \& note(@diagnostic_message);
878 Like \fIdiag()\fR, except the message will not be seen when the test is run
879 in a harness. It will only be visible in the verbose \s-1TAP\s0 stream.
881 Handy for putting in notes which might be useful for debugging, but
882 don't indicate a problem.
885 \& note("Tempfile is $tempfile");
887 .IP "\fBexplain\fR" 4
890 \& my @dump = explain @diagnostic_message;
893 Will dump the contents of any references in a human readable format.
894 Usually you want to pass this into \f(CW\*(C`note\*(C'\fR or \f(CW\*(C`diag\*(C'\fR.
896 Handy for things like...
899 \& is_deeply($have, $want) || diag explain $have;
905 \& note explain \e%args;
906 \& Some::Class\->method(%args);
908 .Sh "Conditional tests"
909 .IX Subsection "Conditional tests"
910 Sometimes running a test under certain conditions will cause the
911 test script to die. A certain function or method isn't implemented
912 (such as \fIfork()\fR on MacOS), some resource isn't available (like a
913 net connection) or a module isn't available. In these cases it's
914 necessary to skip tests, or declare that they are supposed to fail
915 but will work in the future (a todo test).
917 For more details on the mechanics of skip and todo tests see
920 The way Test::More handles this is with a named block. Basically, a
921 block of tests which can be skipped over or made todo. It's best if I
923 .IP "\fB\s-1SKIP:\s0 \s-1BLOCK\s0\fR" 4
924 .IX Item "SKIP: BLOCK"
927 \& skip $why, $how_many if $condition;
931 \& ...normal testing code goes here...
935 This declares a block of tests that might be skipped, \f(CW$how_many\fR tests
936 there are, \f(CW$why\fR and under what \f(CW$condition\fR to skip them. An example is
937 the easiest way to illustrate:
941 \& eval { require HTML::Lint };
945 \& skip "HTML::Lint not installed", 2 if $@;
949 \& my $lint = new HTML::Lint;
950 \& isa_ok( $lint, "HTML::Lint" );
954 \& $lint\->parse( $html );
955 \& is( $lint\->errors, 0, "No errors found in HTML" );
959 If the user does not have HTML::Lint installed, the whole block of
960 code \fIwon't be run at all\fR. Test::More will output special ok's
961 which Test::Harness interprets as skipped, but passing, tests.
963 It's important that \f(CW$how_many\fR accurately reflects the number of tests
964 in the \s-1SKIP\s0 block so the # of tests run will match up with your plan.
965 If your plan is \f(CW\*(C`no_plan\*(C'\fR \f(CW$how_many\fR is optional and will default to 1.
967 It's perfectly safe to nest \s-1SKIP\s0 blocks. Each \s-1SKIP\s0 block must have
968 the label \f(CW\*(C`SKIP\*(C'\fR, or Test::More can't work its magic.
970 You don't skip tests which are failing because there's a bug in your
971 program, or for which you don't yet have code written. For that you
972 use \s-1TODO\s0. Read on.
973 .IP "\fB\s-1TODO:\s0 \s-1BLOCK\s0\fR" 4
974 .IX Item "TODO: BLOCK"
977 \& local $TODO = $why if $condition;
981 \& ...normal testing code goes here...
985 Declares a block of tests you expect to fail and \f(CW$why\fR. Perhaps it's
986 because you haven't fixed a bug or haven't finished a new feature:
990 \& local $TODO = "URI::Geller not finished";
994 \& my $card = "Eight of clubs";
995 \& is( URI::Geller\->your_card, $card, 'Is THIS your card?' );
1000 \& URI::Geller\->bend_spoon;
1001 \& is( $spoon, 'bent', "Spoon bending, that's original" );
1005 With a todo block, the tests inside are expected to fail. Test::More
1006 will run the tests normally, but print out special flags indicating
1007 they are \*(L"todo\*(R". Test::Harness will interpret failures as being ok.
1008 Should anything succeed, it will report it as an unexpected success.
1009 You then know the thing you had todo is done and can remove the
1012 The nice part about todo tests, as opposed to simply commenting out a
1013 block of tests, is it's like having a programmatic todo list. You know
1014 how much work is left to be done, you're aware of what bugs there are,
1015 and you'll know immediately when they're fixed.
1017 Once a todo test starts succeeding, simply move it outside the block.
1018 When the block is empty, delete it.
1019 .IP "\fBtodo_skip\fR" 4
1020 .IX Item "todo_skip"
1023 \& todo_skip $why, $how_many if $condition;
1027 \& ...normal testing code...
1031 With todo tests, it's best to have the tests actually run. That way
1032 you'll know when they start passing. Sometimes this isn't possible.
1033 Often a failing test will cause the whole program to die or hang, even
1034 inside an \f(CW\*(C`eval BLOCK\*(C'\fR with and using \f(CW\*(C`alarm\*(C'\fR. In these extreme
1035 cases you have no choice but to skip over the broken tests entirely.
1037 The syntax and behavior is similar to a \f(CW\*(C`SKIP: BLOCK\*(C'\fR except the
1038 tests will be marked as failing but todo. Test::Harness will
1039 interpret them as passing.
1040 .IP "When do I use \s-1SKIP\s0 vs. \s-1TODO\s0?" 4
1041 .IX Item "When do I use SKIP vs. TODO?"
1042 \&\fBIf it's something the user might not be able to do\fR, use \s-1SKIP\s0.
1043 This includes optional modules that aren't installed, running under
1044 an \s-1OS\s0 that doesn't have some feature (like \fIfork()\fR or symlinks), or maybe
1045 you need an Internet connection and one isn't available.
1047 \&\fBIf it's something the programmer hasn't done yet\fR, use \s-1TODO\s0. This
1048 is for any code you haven't written yet, or bugs you have yet to fix,
1049 but want to put tests in your testing script (always a good idea).
1051 .IX Subsection "Test control"
1052 .IP "\fB\s-1BAIL_OUT\s0\fR" 4
1055 \& BAIL_OUT($reason);
1058 Indicates to the harness that things are going so badly all testing
1059 should terminate. This includes the running any additional test scripts.
1061 This is typically used when testing cannot continue such as a critical
1062 module failing to compile or a necessary external utility not being
1063 available such as a database connection failing.
1065 The test will exit with 255.
1067 For even better control look at Test::Most.
1068 .Sh "Discouraged comparison functions"
1069 .IX Subsection "Discouraged comparison functions"
1070 The use of the following functions is discouraged as they are not
1071 actually testing functions and produce no diagnostics to help figure
1072 out what went wrong. They were written before \fIis_deeply()\fR existed
1073 because I couldn't figure out how to display a useful diff of two
1074 arbitrary data structures.
1076 These functions are usually used inside an \fIok()\fR.
1079 \& ok( eq_array(\e@got, \e@expected) );
1082 \&\f(CW\*(C`is_deeply()\*(C'\fR can do that better and with diagnostics.
1085 \& is_deeply( \e@got, \e@expected );
1088 They may be deprecated in future versions.
1089 .IP "\fBeq_array\fR" 4
1092 \& my $is_eq = eq_array(\e@got, \e@expected);
1095 Checks if two arrays are equivalent. This is a deep check, so
1096 multi-level structures are handled correctly.
1097 .IP "\fBeq_hash\fR" 4
1100 \& my $is_eq = eq_hash(\e%got, \e%expected);
1103 Determines if the two hashes contain the same keys and values. This
1105 .IP "\fBeq_set\fR" 4
1108 \& my $is_eq = eq_set(\e@got, \e@expected);
1111 Similar to \fIeq_array()\fR, except the order of the elements is \fBnot\fR
1112 important. This is a deep check, but the irrelevancy of order only
1113 applies to the top level.
1116 \& ok( eq_set(\e@got, \e@expected) );
1122 \& is_deeply( [sort @got], [sort @expected] );
1125 \&\fB\s-1NOTE\s0\fR By historical accident, this is not a true set comparison.
1126 While the order of elements does not matter, duplicate elements do.
1128 \&\fB\s-1NOTE\s0\fR \fIeq_set()\fR does not know how to deal with references at the top
1129 level. The following is an example of a comparison which might not work:
1132 \& eq_set([\e1, \e2], [\e2, \e1]);
1135 Test::Deep contains much better set comparison functions.
1136 .Sh "Extending and Embedding Test::More"
1137 .IX Subsection "Extending and Embedding Test::More"
1138 Sometimes the Test::More interface isn't quite enough. Fortunately,
1139 Test::More is built on top of Test::Builder which provides a single,
1140 unified backend for any test library to use. This means two test
1141 libraries which both use Test::Builder \fBcan be used together in the
1144 If you simply want to do a little tweaking of how the tests behave,
1145 you can access the underlying Test::Builder object like so:
1146 .IP "\fBbuilder\fR" 4
1149 \& my $test_builder = Test::More\->builder;
1152 Returns the Test::Builder object underlying Test::More for you to play
1155 .IX Header "EXIT CODES"
1156 If all your tests passed, Test::Builder will exit with zero (which is
1157 normal). If anything failed it will exit with how many failed. If
1158 you run less (or more) tests than you planned, the missing (or extras)
1159 will be considered failures. If no tests were ever run Test::Builder
1160 will throw a warning and exit with 255. If the test died, even after
1161 having successfully completed all its tests, it will still be
1162 considered a failure and will exit with 255.
1164 So the exit codes are...
1167 \& 0 all tests successful
1168 \& 255 test died or all passed but wrong # of tests run
1169 \& any other number how many failed (including missing or extras)
1172 If you fail more than 254 tests, it will be reported as 254.
1174 \&\fB\s-1NOTE\s0\fR This behavior may go away in future versions.
1175 .SH "CAVEATS and NOTES"
1176 .IX Header "CAVEATS and NOTES"
1177 .IP "Backwards compatibility" 4
1178 .IX Item "Backwards compatibility"
1179 Test::More works with Perls as old as 5.6.0.
1180 .ie n .IP "utf8 / ""Wide character in print""" 4
1181 .el .IP "utf8 / ``Wide character in print''" 4
1182 .IX Item "utf8 / Wide character in print"
1183 If you use utf8 or other non-ASCII characters with Test::More you
1184 might get a \*(L"Wide character in print\*(R" warning. Using \f(CW\*(C`binmode
1185 STDOUT, ":utf8"\*(C'\fR will not fix it. Test::Builder (which powers
1186 Test::More) duplicates \s-1STDOUT\s0 and \s-1STDERR\s0. So any changes to them,
1187 including changing their output disciplines, will not be seem by
1190 The work around is to change the filehandles used by Test::Builder
1194 \& my $builder = Test::More\->builder;
1195 \& binmode $builder\->output, ":utf8";
1196 \& binmode $builder\->failure_output, ":utf8";
1197 \& binmode $builder\->todo_output, ":utf8";
1199 .IP "Overloaded objects" 4
1200 .IX Item "Overloaded objects"
1201 String overloaded objects are compared \fBas strings\fR (or in \fIcmp_ok()\fR's
1202 case, strings or numbers as appropriate to the comparison op). This
1203 prevents Test::More from piercing an object's interface allowing
1204 better blackbox testing. So if a function starts returning overloaded
1205 objects instead of bare strings your tests won't notice the
1206 difference. This is good.
1208 However, it does mean that functions like \fIis_deeply()\fR cannot be used to
1209 test the internals of string overloaded objects. In this case I would
1210 suggest Test::Deep which contains more flexible testing functions for
1211 complex data structures.
1214 Test::More will only be aware of threads if \*(L"use threads\*(R" has been done
1215 \&\fIbefore\fR Test::More is loaded. This is ok:
1222 This may cause problems:
1229 5.8.1 and above are supported. Anything below that has too many bugs.
1231 .IX Header "HISTORY"
1232 This is a case of convergent evolution with Joshua Pritikin's Test
1233 module. I was largely unaware of its existence when I'd first
1234 written my own \fIok()\fR routines. This module exists because I can't
1235 figure out how to easily wedge test names into Test's interface (along
1236 with a few other problems).
1238 The goal here is to have a testing utility that's simple to learn,
1239 quick to use and difficult to trip yourself up with while still
1240 providing more flexibility than the existing Test.pm. As such, the
1241 names of the most common routines are kept tiny, special cases and
1242 magic side-effects are kept to a minimum. \s-1WYSIWYG\s0.
1244 .IX Header "SEE ALSO"
1245 Test::Simple if all this confuses you and you just want to write
1246 some tests. You can upgrade to Test::More later (it's forward
1249 Test::Harness is the test runner and output interpreter for Perl.
1250 It's the thing that powers \f(CW\*(C`make test\*(C'\fR and where the \f(CW\*(C`prove\*(C'\fR utility
1253 Test::Legacy tests written with Test.pm, the original testing
1254 module, do not play well with other testing libraries. Test::Legacy
1255 emulates the Test.pm interface and does play well with others.
1257 Test::Differences for more ways to test complex data structures.
1258 And it plays well with Test::More.
1260 Test::Class is like xUnit but more perlish.
1262 Test::Deep gives you more powerful complex data structure testing.
1264 Test::Inline shows the idea of embedded testing.
1266 Bundle::Test installs a whole bunch of useful test modules.
1268 .IX Header "AUTHORS"
1269 Michael G Schwern <schwern@pobox.com> with much inspiration
1270 from Joshua Pritikin's Test module and lots of help from Barrie
1271 Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and
1275 See \fIhttp://rt.cpan.org\fR to report and view bugs.
1278 The source code repository for Test::More can be found at
1279 \&\fIhttp://github.com/schwern/test\-more/\fR.
1281 .IX Header "COPYRIGHT"
1282 Copyright 2001\-2008 by Michael G Schwern <schwern@pobox.com>.
1284 This program is free software; you can redistribute it and/or
1285 modify it under the same terms as Perl itself.
1287 See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR
projects / catagits/Gitalist.git / blob