12 my(@Test_Results) = ();
13 my($Num_Tests, $Planned_Tests, $Test_Died) = (0,0,0);
16 my $IsVMS = $^O eq 'VMS';
19 # I'd like to have Test::Simple interfere with the program being
20 # tested as little as possible. This includes using Exporter or
21 # anything else (including strict).
25 if( $_[1] eq 'no_plan' ) {
35 my($class, %config) = @_;
37 if( !exists $config{tests} ) {
38 die "You have to tell $class how many tests you plan to run.\n".
39 " use $class tests => 42; for example.\n";
41 elsif( !defined $config{tests} ) {
42 die "Got an undefined number of tests. Looks like you tried to tell ".
43 "$class how many tests you plan to run but made a mistake.\n";
45 elsif( !$config{tests} ) {
46 die "You told $class you plan to run 0 tests! You've got to run ".
50 $Planned_Tests = $config{tests};
55 my_print *TESTOUT, "1..$Planned_Tests\n";
59 *{$caller.'::ok'} = \&ok;
69 *{$caller.'::ok'} = \&ok;
75 open(*TESTOUT, ">&STDOUT") or _whoa(1, "Can't dup STDOUT!");
76 open(*TESTERR, ">&STDOUT") or _whoa(1, "Can't dup STDOUT!");
78 my $orig_fh = select TESTOUT;
88 Test::Simple - Basic utilities for writing tests.
92 use Test::Simple tests => 1;
94 ok( $foo eq $bar, 'foo is bar' );
99 ** If you are unfamiliar with testing B<read Test::Tutorial> first! **
101 This is an extremely simple, extremely basic module for writing tests
102 suitable for CPAN modules and other pursuits. If you wish to do more
103 complicated testing, use the Test::More module (a drop-in replacement
106 The basic unit of Perl testing is the ok. For each thing you want to
107 test your program will print out an "ok" or "not ok" to indicate pass
108 or fail. You do this with the ok() function (see below).
110 The only other constraint is you must predeclare how many tests you
111 plan to run. This is in case something goes horribly wrong during the
112 test and your test program aborts, or skips a test or whatever. You
115 use Test::Simple tests => 23;
117 You must have a plan.
124 ok( $foo eq $bar, $name );
127 ok() is given an expression (in this case C<$foo eq $bar>). If its
128 true, the test passed. If its false, it didn't. That's about it.
130 ok() prints out either "ok" or "not ok" along with a test number (it
131 keeps track of that for you).
133 # This produces "ok 1 - Hell not yet frozen over" (or not ok)
134 ok( get_temperature($hell) > 0, 'Hell not yet frozen over' );
136 If you provide a $name, that will be printed along with the "ok/not
137 ok" to make it easier to find your test when if fails (just search for
138 the name). It also makes it easier for the next guy to understand
139 what your test is for. Its highly recommended you use test names.
141 All tests are run in scalar context. So this:
143 ok( @stuff, 'I have some stuff' );
145 will do what you mean (fail if stuff is empty)
150 my($test, $name) = @_;
152 unless( $Have_Plan ) {
153 die "You tried to use ok() without a plan! Gotta have a plan.\n".
154 " use Test::Simple tests => 23; for example.\n";
159 my_print *TESTERR, <<ERR if defined $name and $name =~ /^[\d\s]+$/;
160 You named your test '$name'. You shouldn't use numbers for your test names.
165 my($pack, $file, $line) = caller;
166 # temporary special case for Test::More & Parrot::Test's calls.
167 if( $pack eq 'Test::More' || $pack eq 'Parrot::Test' ) {
168 ($pack, $file, $line) = caller(1);
171 my($is_todo) = ${$pack.'::TODO'} ? 1 : 0;
173 # We must print this all in one shot or else it will break on VMS
177 $Test_Results[$Num_Tests-1] = $is_todo ? 1 : 0;
180 $Test_Results[$Num_Tests-1] = 1;
182 $msg .= "ok $Num_Tests";
184 if( defined $name ) {
185 $name =~ s|#|\\#|g; # # in a name can confuse Test::Harness.
189 my $what_todo = ${$pack.'::TODO'};
190 $msg .= " # TODO $what_todo";
194 my_print *TESTOUT, $msg;
198 my $msg = $is_todo ? "Failed (TODO)" : "Failed";
199 my_print *TESTERR, "# $msg test ($file at line $line)\n";
202 return $test ? 1 : 0;
209 unless( $Have_Plan ) {
210 die "You tried to use ok() without a plan! Gotta have a plan.\n".
211 " use Test::Simple tests => 23; for example.\n";
216 # XXX Set this to "Skip" instead?
217 $Test_Results[$Num_Tests-1] = 1;
219 # We must print this all in one shot or else it will break on VMS
221 $msg .= "ok $Num_Tests # skip $why\n";
223 my_print *TESTOUT, $msg;
231 Test::Simple will start by printing number of tests run in the form
232 "1..M" (so "1..5" means you're going to run 5 tests). This strange
233 format lets Test::Harness know how many tests you plan on running in
234 case something goes horribly wrong.
236 If all your tests passed, Test::Simple will exit with zero (which is
237 normal). If anything failed it will exit with how many failed. If
238 you run less (or more) tests than you planned, the missing (or extras)
239 will be considered failures. If no tests were ever run Test::Simple
240 will throw a warning and exit with 255. If the test died, even after
241 having successfully completed all its tests, it will still be
242 considered a failure and will exit with 255.
244 So the exit codes are...
246 0 all tests successful
248 any other number how many failed (including missing or extras)
250 If you fail more than 254 tests, it will be reported as 254.
256 =item B<_sanity_check>
260 Runs a bunch of end of test sanity checks to make sure reality came
261 through ok. If anything is wrong it will die with a fairly friendly
268 _whoa($Num_Tests < 0, 'Says here you ran a negative number of tests!');
269 _whoa(!$Have_Plan and $Num_Tests,
270 'Somehow your tests ran without a plan!');
271 _whoa($Num_Tests != @Test_Results,
272 'Somehow you got a different number of results than tests ran!');
277 _whoa($check, $description);
279 A sanity check, similar to assert(). If the $check is true, something
280 has gone horribly wrong. It will die with the given $description and
281 a note to contact the author.
286 my($check, $desc) = @_;
290 This should never happen! Please contact the author immediately!
299 Perl seems to have some trouble with exiting inside an END block. 5.005_03
300 and 5.6.1 both seem to do odd things. Instead, this function edits $?
301 directly. It should ONLY be called from inside an END block. It
302 doesn't actually exit, that's your job.
319 $SIG{__DIE__} = sub {
320 # We don't want to muck with death in an eval, but $^S isn't
321 # totally reliable. 5.005_03 and 5.6.1 both do the wrong thing
322 # with it. Instead, we use caller. This also means it runs under
325 for( my $stack = 1; my $sub = (caller($stack))[3]; $stack++ ) {
326 $in_eval = 1 if $sub =~ /^\(eval\)/;
328 $Test_Died = 1 unless $in_eval;
334 # Bailout if import() was never called. This is so
335 # "require Test::Simple" doesn't puke.
336 do{ _my_exit(0) && return } if !$Have_Plan and !$Num_Tests;
338 # Figure out if we passed or failed and print helpful messages.
340 # The plan? We have no plan.
341 unless( $Planned_Tests ) {
342 my_print *TESTOUT, "1..$Num_Tests\n";
343 $Planned_Tests = $Num_Tests;
346 my $num_failed = grep !$_, @Test_Results[0..$Planned_Tests-1];
347 $num_failed += abs($Planned_Tests - @Test_Results);
349 if( $Num_Tests < $Planned_Tests ) {
350 my_print *TESTERR, <<"FAIL";
351 # Looks like you planned $Planned_Tests tests but only ran $Num_Tests.
354 elsif( $Num_Tests > $Planned_Tests ) {
355 my $num_extra = $Num_Tests - $Planned_Tests;
356 my_print *TESTERR, <<"FAIL";
357 # Looks like you planned $Planned_Tests tests but ran $num_extra extra.
360 elsif ( $num_failed ) {
361 my_print *TESTERR, <<"FAIL";
362 # Looks like you failed $num_failed tests of $Planned_Tests.
367 my_print *TESTERR, <<"FAIL";
368 # Looks like your test died just after $Num_Tests.
371 _my_exit( 255 ) && return;
374 _my_exit( $num_failed <= 254 ? $num_failed : 254 ) && return;
376 elsif ( $Test::Simple::Skip_All ) {
377 _my_exit( 0 ) && return;
380 my_print *TESTERR, "# No tests run!\n";
381 _my_exit( 255 ) && return;
388 This module is by no means trying to be a complete testing system.
389 Its just to get you started. Once you're off the ground its
390 recommended you look at L<Test::More>.
395 Here's an example of a simple .t file for the fictional Film module.
397 use Test::Simple tests => 5;
399 use Film; # What you're testing.
401 my $btaste = Film->new({ Title => 'Bad Taste',
402 Director => 'Peter Jackson',
404 NumExplodingSheep => 1
406 ok( defined($btaste) and ref $btaste eq 'Film', 'new() works' );
408 ok( $btaste->Title eq 'Bad Taste', 'Title() get' );
409 ok( $btaste->Director eq 'Peter Jackson', 'Director() get' );
410 ok( $btaste->Rating eq 'R', 'Rating() get' );
411 ok( $btaste->NumExplodingSheep == 1, 'NumExplodingSheep() get' );
413 It will produce output like this:
418 ok 3 - Director() get
419 not ok 4 - Rating() get
420 # Failed test (t/film.t at line 14)
421 ok 5 - NumExplodingSheep() get
422 # Looks like you failed 1 tests of 5
424 Indicating the Film::Rating() method is broken.
429 Test::Simple will only report a maximum of 254 failures in its exit
430 code. If this is a problem, you probably have a huge test script.
431 Split it into multiple files. (Otherwise blame the Unix folks for
432 using an unsigned short integer as the exit status).
434 Because VMS's exit codes are much, much different than the rest of the
435 universe, and perl does horrible mangling to them that gets in my way,
436 it works like this on VMS.
438 0 SS$_NORMAL all tests successful
439 4 SS$_ABORT something went wrong
441 Unfortunately, I can't differentiate any further.
446 Test::Simple is B<explicitly> tested all the way back to perl 5.004.
451 This module was conceived while talking with Tony Bowden in his
452 kitchen one night about the problems I was having writing some really
453 complicated feature into the new Testing module. He observed that the
454 main problem is not dealing with these edge cases but that people hate
455 to write tests B<at all>. What was needed was a dead simple module
456 that took all the hard work out of testing and was really, really easy
457 to learn. Paul Johnson simultaneously had this idea (unfortunately,
458 he wasn't in Tony's kitchen). This is it.
463 Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern
464 E<lt>schwern@pobox.comE<gt>, wardrobe by Calvin Klein.
473 More testing functions! Once you outgrow Test::Simple, look at
474 Test::More. Test::Simple is 100% forward compatible with Test::More
475 (ie. you can just use Test::More instead of Test::Simple in your
476 programs and things will still work).
480 The original Perl testing module.
484 Elaborate unit testing.
486 =item L<Pod::Tests>, L<SelfTest>
488 Embed tests in your code!
490 =item L<Test::Harness>
492 Interprets the output of your test program.