11 *TESTOUT = \*Test::Simple::TESTOUT;
12 *TESTERR = \*Test::Simple::TESTERR;
16 use vars qw($VERSION @ISA @EXPORT $TODO);
19 @EXPORT = qw(ok use_ok require_ok
23 eq_array eq_hash eq_set
32 my($class, $plan, @args) = @_;
35 if( $plan eq 'skip_all' ) {
36 $Test::Simple::Skip_All = 1;
38 $out .= " # Skip @args" if @args;
41 my_print *TESTOUT, $out;
45 Test::Simple->import($plan => @args);
52 __PACKAGE__->_export_to_level(1, __PACKAGE__);
55 # 5.004's Exporter doesn't have export_to_level.
60 (undef) = shift; # XXX redundant arg
61 my $callpkg = caller($level);
62 $pkg->export($callpkg, @_);
68 Test::More - yet another framework for writing test scripts
72 use Test::More tests => $Num_Tests;
74 use Test::More qw(no_plan);
76 use Test::More skip_all => $reason;
78 BEGIN { use_ok( 'Some::Module' ); }
79 require_ok( 'Some::Module' );
81 # Various ways to say "ok"
82 ok($this eq $that, $test_name);
84 is ($this, $that, $test_name);
85 isnt($this, $that, $test_name);
86 like($this, qr/that/, $test_name);
89 skip $why, $how_many unless $have_some_feature;
91 ok( foo(), $test_name );
92 is( foo(42), 23, $test_name );
98 ok( foo(), $test_name );
99 is( foo(42), 23, $test_name );
102 can_ok($module, @methods);
103 isa_ok($object, $class);
108 # Utility comparison functions.
109 eq_array(\@this, \@that);
110 eq_hash(\%this, \%that);
111 eq_set(\@this, \@that);
114 my @status = Test::More::status;
122 If you're just getting started writing tests, have a look at
123 Test::Simple first. This is a drop in replacement for Test::Simple
124 which you can switch to once you get the hang of basic testing.
126 This module provides a very wide range of testing utilities. Various
127 ways to say "ok", facilities to skip tests, test future features
128 and compare complicated data structures.
131 =head2 I love it when a plan comes together
133 Before anything else, you need a testing plan. This basically declares
134 how many tests your script is going to run to protect against premature
137 The prefered way to do this is to declare a plan when you C<use Test::More>.
139 use Test::More tests => $Num_Tests;
141 There are rare cases when you will not know beforehand how many tests
142 your script is going to run. In this case, you can declare that you
143 have no plan. (Try to avoid using this as it weakens your test.)
145 use Test::More qw(no_plan);
147 In some cases, you'll want to completely skip an entire testing script.
149 use Test::More skip_all => $skip_reason;
151 Your script will declare a skip with the reason why you skipped and
152 exit immediately with a zero (success). See L<Test::Harness> for
158 By convention, each test is assigned a number in order. This is
159 largely done automatically for you. However, its often very useful to
160 assign a name to each test. Which would you rather see:
168 ok 4 - basic multi-variable
169 not ok 5 - simple exponential
170 ok 6 - force == mass * acceleration
172 The later gives you some idea of what failed. It also makes it easier
173 to find the test in your script, simply search for "simple
176 All test functions take a name argument. Its optional, but highly
177 suggested that you use it.
180 =head2 I'm ok, you're not ok.
182 The basic purpose of this module is to print out either "ok #" or "not
183 ok #" depending on if a given test succeeded or failed. Everything
186 All of the following print "ok" or "not ok" depending on if the test
187 succeeded or failed. They all also return true or false,
194 ok($this eq $that, $test_name);
196 This simply evaluates any expression (C<$this eq $that> is just a
197 simple example) and uses that to determine if the test succeeded or
198 failed. A true expression passes, a false one fails. Very simple.
202 ok( $exp{9} == 81, 'simple exponential' );
203 ok( Film->can('db_Main'), 'set_db()' );
204 ok( $p->tests == 4, 'saw tests' );
205 ok( !grep !defined $_, @items, 'items populated' );
207 (Mnemonic: "This is ok.")
209 $test_name is a very short description of the test that will be printed
210 out. It makes it very easy to find a test in your script when it fails
211 and gives others an idea of your intentions. $test_name is optional,
212 but we B<very> strongly encourage its use.
214 Should an ok() fail, it will produce some diagnostics:
216 not ok 18 - sufficient mucus
217 # Failed test 18 (foo.t at line 42)
219 This is actually Test::Simple's ok() routine.
223 # We get ok() from Test::Simple's import().
229 is ( $this, $that, $test_name );
230 isnt( $this, $that, $test_name );
232 Similar to ok(), is() and isnt() compare their two arguments
233 with C<eq> and C<ne> respectively and use the result of that to
234 determine if the test succeeded or failed. So these:
236 # Is the ultimate answer 42?
237 is( ultimate_answer(), 42, "Meaning of Life" );
240 isnt( $foo, '', "Got some foo" );
242 are similar to these:
244 ok( ultimate_answer() eq 42, "Meaning of Life" );
245 ok( $foo ne '', "Got some foo" );
247 (Mnemonic: "This is that." "This isn't that.")
249 So why use these? They produce better diagnostics on failure. ok()
250 cannot know what you are testing for (beyond the name), but is() and
251 isnt() know what the test was and why it failed. For example this
254 my $foo = 'waffle'; my $bar = 'yarblokos';
255 is( $foo, $bar, 'Is foo the same as bar?' );
257 Will produce something like this:
259 not ok 17 - Is foo the same as bar?
260 # Failed test 1 (foo.t at line 139)
262 # expected: 'yarblokos'
264 So you can figure out what went wrong without rerunning the test.
266 You are encouraged to use is() and isnt() over ok() where possible,
267 however do not be tempted to use them to find out if something is
270 # XXX BAD! $pope->isa('Catholic') eq 1
271 is( $pope->isa('Catholic'), 1, 'Is the Pope Catholic?' );
273 This does not check if C<$pope->isa('Catholic')> is true, it checks if
274 it returns 1. Very different. Similar caveats exist for false and 0.
275 In these cases, use ok().
277 ok( $pope->isa('Catholic') ), 'Is the Pope Catholic?' );
279 For those grammatical pedants out there, there's an C<isn't()>
280 function which is an alias of isnt().
285 my($this, $that, $name) = @_;
289 local $^W = 0; # so is(undef, undef) works quietly.
290 $test = $this eq $that;
292 my $ok = @_ == 3 ? ok($test, $name)
296 $this = defined $this ? "'$this'" : 'undef';
297 $that = defined $that ? "'$that'" : 'undef';
298 my_print *TESTERR, sprintf <<DIAGNOSTIC, $this, $that;
309 my($this, $that, $name) = @_;
313 local $^W = 0; # so isnt(undef, undef) works quietly.
314 $test = $this ne $that;
317 my $ok = @_ == 3 ? ok($test, $name)
321 $that = defined $that ? "'$that'" : 'undef';
323 my_print *TESTERR, sprintf <<DIAGNOSTIC, $that;
324 # it should not be %s
338 like( $this, qr/that/, $test_name );
340 Similar to ok(), like() matches $this against the regex C<qr/that/>.
344 like($this, qr/that/, 'this is like that');
348 ok( $this =~ /that/, 'this is like that');
350 (Mnemonic "This is like that".)
352 The second argument is a regular expression. It may be given as a
353 regex reference (ie. C<qr//>) or (for better compatibility with older
354 perls) as a string that looks like a regex (alternative delimiters are
355 currently not supported):
357 like( $this, '/that/', 'this is like that' );
359 Regex options may be placed on the end (C<'/that/i'>).
361 Its advantages over ok() are similar to that of is() and isnt(). Better
362 diagnostics on failure.
367 my($this, $regex, $name) = @_;
370 if( ref $regex eq 'Regexp' ) {
372 $ok = @_ == 3 ? ok( $this =~ $regex ? 1 : 0, $name )
373 : ok( $this =~ $regex ? 1 : 0 );
375 # Check if it looks like '/foo/i'
376 elsif( my($re, $opts) = $regex =~ m{^ /(.*)/ (\w*) $ }sx ) {
378 $ok = @_ == 3 ? ok( $this =~ /(?$opts)$re/ ? 1 : 0, $name )
379 : ok( $this =~ /(?$opts)$re/ ? 1 : 0 );
382 # Can't use fail() here, the call stack will be fucked.
383 my $ok = @_ == 3 ? ok(0, $name )
386 my_print *TESTERR, <<ERR;
387 # '$regex' doesn't look much like a regex to me. Failing the test.
394 $this = defined $this ? "'$this'" : 'undef';
395 my_print *TESTERR, sprintf <<DIAGNOSTIC, $this;
397 # doesn't match '$regex'
407 can_ok($module, @methods);
408 can_ok($object, @methods);
410 Checks to make sure the $module or $object can do these @methods
411 (works with functions, too).
413 can_ok('Foo', qw(this that whatever));
415 is almost exactly like saying:
417 ok( Foo->can('this') &&
422 only without all the typing and with a better interface. Handy for
423 quickly testing an interface.
428 my($proto, @methods) = @_;
429 my $class= ref $proto || $proto;
432 foreach my $method (@methods) {
433 my $test = "$class->can('$method')";
434 eval $test || push @nok, $method;
438 $name = @methods == 1 ? "$class->can($methods[0])"
439 : "$class->can(...)";
443 my_print *TESTERR, map "# $class->can('$_') failed\n", @nok;
450 isa_ok($object, $class);
452 Checks to see if the given $object->isa($class). Also checks to make
453 sure the object was defined in the first place. Handy for this sort
456 my $obj = Some::Module->new;
457 isa_ok( $obj, 'Some::Module' );
459 where you'd otherwise have to write
461 my $obj = Some::Module->new;
462 ok( defined $obj && $obj->isa('Some::Module') );
464 to safeguard against your test script blowing up.
469 my($object, $class) = @_;
472 my $name = "object->isa('$class')";
473 if( !defined $object ) {
474 $diag = "The object isn't defined";
476 elsif( !ref $object ) {
477 $diag = "The object isn't a reference";
479 elsif( !$object->isa($class) ) {
480 $diag = "The object isn't a '$class'";
485 my_print *TESTERR, "# $diag\n";
502 Sometimes you just want to say that the tests have passed. Usually
503 the case is you've got some complicated condition that is difficult to
504 wedge into an ok(). In this case, you can simply use pass() (to
505 declare the test ok) or fail (for not ok). They are synonyms for
508 Use these very, very, very sparingly.
514 return @_ == 1 ? ok(1, $name)
520 return @_ == 1 ? ok(0, $name)
528 You usually want to test if the module you're testing loads ok, rather
529 than just vomiting if its load fails. For such purposes we have
530 C<use_ok> and C<require_ok>.
536 BEGIN { use_ok($module); }
537 BEGIN { use_ok($module, @imports); }
539 These simply use the given $module and test to make sure the load
540 happened ok. Its recommended that you run use_ok() inside a BEGIN
541 block so its functions are exported at compile-time and prototypes are
544 If @imports are given, they are passed through to the use. So this:
546 BEGIN { use_ok('Some::Module', qw(foo bar)) }
550 use Some::Module qw(foo bar);
556 my($module, @imports) = @_;
557 @imports = () unless @imports;
564 $module->import(\@imports);
567 my $ok = ok( !$@, "use $module;" );
571 my_print *TESTERR, <<DIAGNOSTIC;
572 # Tried to use '$module'.
585 Like use_ok(), except it requires the $module.
599 my $ok = ok( !$@, "require $module;" );
603 my_print *TESTERR, <<DIAGNOSTIC;
604 # Tried to require '$module'.
615 =head2 Conditional tests
617 B<WARNING!> The following describes an I<experimental> interface that
618 is subject to change B<WITHOUT NOTICE>! Use at your peril.
620 Sometimes running a test under certain conditions will cause the
621 test script to die. A certain function or method isn't implemented
622 (such as fork() on MacOS), some resource isn't available (like a
623 net connection) or a module isn't available. In these cases it's
624 necessary to skip tests, or declare that they are supposed to fail
625 but will work in the future (a todo test).
627 For more details on skip and todo tests see L<Test::Harness>.
629 The way Test::More handles this is with a named block. Basically, a
630 block of tests which can be skipped over or made todo. It's best if I
638 skip $why, $how_many if $condition;
640 ...normal testing code goes here...
643 This declares a block of tests to skip, $how_many tests there are,
644 $why and under what $condition to skip them. An example is the
645 easiest way to illustrate:
648 skip "Pigs don't fly here", 2 unless Pigs->can('fly');
653 ok( $pig->altitude > 0, 'Pig is airborne' );
654 ok( $pig->airspeed > 0, ' and moving' );
657 If pigs cannot fly, the whole block of tests will be skipped
658 completely. Test::More will output special ok's which Test::Harness
659 interprets as skipped tests. Its important to include $how_many tests
660 are in the block so the total number of tests comes out right (unless
661 you're using C<no_plan>).
663 You'll typically use this when a feature is missing, like an optional
664 module is not installed or the operating system doesn't have some
665 feature (like fork() or symlinks) or maybe you need an Internet
666 connection and one isn't available.
669 See L</Why are skip and todo so weird?>
675 my($why, $how_many) = @_;
676 unless( $how_many >= 1 ) {
677 # $how_many can only be avoided when no_plan is in use.
678 carp "skip() needs to know \$how_many tests are in the block"
679 if $Test::Simple::Planned_Tests;
683 for( 1..$how_many ) {
684 Test::Simple::_skipped($why);
697 ...normal testing code goes here...
700 Declares a block of tests you expect to fail and $why. Perhaps it's
701 because you haven't fixed a bug or haven't finished a new feature:
704 local $TODO = "URI::Geller not finished";
706 my $card = "Eight of clubs";
707 is( URI::Geller->your_card, $card, 'Is THIS your card?' );
710 URI::Geller->bend_spoon;
711 is( $spoon, 'bent', "Spoon bending, that's original" );
714 With a todo block, the tests inside are expected to fail. Test::More
715 will run the tests normally, but print out special flags indicating
716 they are "todo". Test::Harness will interpret failures as being ok.
717 Should anything succeed, it will report it as an unexpected success.
719 The nice part about todo tests, as opposed to simply commenting out a
720 block of tests, is it's like having a programatic todo list. You know
721 how much work is left to be done, you're aware of what bugs there are,
722 and you'll know immediately when they're fixed.
724 Once a todo test starts succeeding, simply move it outside the block.
725 When the block is empty, delete it.
730 =head2 Comparision functions
732 Not everything is a simple eq check or regex. There are times you
733 need to see if two arrays are equivalent, for instance. For these
734 instances, Test::More provides a handful of useful functions.
736 B<NOTE> These are NOT well-tested on circular references. Nor am I
737 quite sure what will happen with filehandles.
743 eq_array(\@this, \@that);
745 Checks if two arrays are equivalent. This is a deep check, so
746 multi-level structures are handled correctly.
753 return 0 unless @$a1 == @$a2;
754 return 1 if $a1 eq $a2;
758 my($e1,$e2) = ($a1->[$_], $a2->[$_]);
759 $ok = _deep_check($e1,$e2);
771 # Quiet unintialized value warnings when comparing undefs.
778 if( UNIVERSAL::isa($e1, 'ARRAY') and
779 UNIVERSAL::isa($e2, 'ARRAY') )
781 $ok = eq_array($e1, $e2);
783 elsif( UNIVERSAL::isa($e1, 'HASH') and
784 UNIVERSAL::isa($e2, 'HASH') )
786 $ok = eq_hash($e1, $e2);
800 eq_hash(\%this, \%that);
802 Determines if the two hashes contain the same keys and values. This
809 return 0 unless keys %$a1 == keys %$a2;
810 return 1 if $a1 eq $a2;
813 foreach my $k (keys %$a1) {
814 my($e1, $e2) = ($a1->{$k}, $a2->{$k});
815 $ok = _deep_check($e1, $e2);
824 eq_set(\@this, \@that);
826 Similar to eq_array(), except the order of the elements is B<not>
827 important. This is a deep check, but the irrelevancy of order only
828 applies to the top level.
832 # We must make sure that references are treated neutrally. It really
833 # doesn't matter how we sort them, as long as both arrays are sorted
834 # with the same algorithm.
835 sub _bogus_sort { local $^W = 0; ref $a ? 0 : $a cmp $b }
839 return 0 unless @$a1 == @$a2;
841 # There's faster ways to do this, but this is easiest.
842 return eq_array( [sort _bogus_sort @$a1], [sort _bogus_sort @$a2] );
850 Test::More is B<explicitly> tested all the way back to perl 5.004.
852 =head1 BUGS and CAVEATS
856 =item Making your own ok()
858 This will not do what you mean:
864 my_ok( 2 + 2 == 5, 'Basic addition' );
866 since ok() takes it's arguments as scalars, it will see the length of
867 @_ (2) and always pass the test. You want to do this instead:
873 The other functions act similiarly.
875 =item The eq_* family have some caveats.
877 =item Test::Harness upgrades
879 no_plan and todo depend on new Test::Harness features and fixes. If
880 you're going to distribute tests that use no_plan your end-users will
881 have to upgrade Test::Harness to the latest one on CPAN.
883 If you simply depend on Test::More, it's own dependencies will cause a
884 Test::Harness upgrade.
890 Michael G Schwern E<lt>schwern@pobox.comE<gt> with much inspiration from
891 Joshua Pritikin's Test module and lots of discussion with Barrie
892 Slaymaker and the perl-qa gang.
897 This is a case of convergent evolution with Joshua Pritikin's Test
898 module. I was largely unware of its existence when I'd first
899 written my own ok() routines. This module exists because I can't
900 figure out how to easily wedge test names into Test's interface (along
901 with a few other problems).
903 The goal here is to have a testing utility that's simple to learn,
904 quick to use and difficult to trip yourself up with while still
905 providing more flexibility than the existing Test.pm. As such, the
906 names of the most common routines are kept tiny, special cases and
907 magic side-effects are kept to a minimum. WYSIWYG.
912 L<Test::Simple> if all this confuses you and you just want to write
913 some tests. You can upgrade to Test::More later (its forward
916 L<Test> for a similar testing module.
918 L<Test::Harness> for details on how your test results are interpreted
921 L<Test::Unit> describes a very featureful unit testing interface.
923 L<Pod::Tests> shows the idea of embedded testing.
925 L<SelfTest> is another approach to embedded testing.