5 $Test::Simple::VERSION = '0.09';
7 my(@Test_Results) = ();
8 my($Num_Tests, $Planned_Tests, $Test_Died) = (0,0,0);
12 # Special print function to guard against $\ and -l munging.
20 sub print { die "DON'T USE PRINT! Use _print instead" }
23 # I'd like to have Test::Simple interfere with the program being
24 # tested as little as possible. This includes using Exporter or
25 # anything else (including strict).
29 if( $_[1] eq 'no_plan' ) {
39 my($class, %config) = @_;
41 if( !exists $config{tests} ) {
42 die "You have to tell $class how many tests you plan to run.\n".
43 " use $class tests => 42; for example.\n";
45 elsif( !defined $config{tests} ) {
46 die "Got an undefined number of tests. Looks like you tried to tell ".
47 "$class how many tests you plan to run but made a mistake.\n";
49 elsif( !$config{tests} ) {
50 die "You told $class you plan to run 0 tests! You've got to run ".
54 $Planned_Tests = $config{tests};
59 _print *TESTOUT, "1..$Planned_Tests\n";
62 *{$caller.'::ok'} = \&ok;
71 *{$caller.'::ok'} = \&ok;
77 open(*TESTOUT, ">&STDOUT") or _whoa(1, "Can't dup STDOUT!");
78 open(*TESTERR, ">&STDERR") or _whoa(1, "Can't dup STDERR!");
80 my $orig_fh = select TESTOUT;
89 Test::Simple - Basic utilities for writing tests.
93 use Test::Simple tests => 1;
95 ok( $foo eq $bar, 'foo is bar' );
100 This is an extremely simple, extremely basic module for writing tests
101 suitable for CPAN modules and other pursuits.
103 The basic unit of Perl testing is the ok. For each thing you want to
104 test your program will print out an "ok" or "not ok" to indicate pass
105 or fail. You do this with the ok() function (see below).
107 The only other constraint is you must predeclare how many tests you
108 plan to run. This is in case something goes horribly wrong during the
109 test and your test program aborts, or skips a test or whatever. You
112 use Test::Simple tests => 23;
114 You must have a plan.
121 ok( $foo eq $bar, $name );
124 ok() is given an expression (in this case C<$foo eq $bar>). If its
125 true, the test passed. If its false, it didn't. That's about it.
127 ok() prints out either "ok" or "not ok" along with a test number (it
128 keeps track of that for you).
130 # This produces "ok 1 - Hell not yet frozen over" (or not ok)
131 ok( get_temperature($hell) > 0, 'Hell not yet frozen over' );
133 If you provide a $name, that will be printed along with the "ok/not
134 ok" to make it easier to find your test when if fails (just search for
135 the name). It also makes it easier for the next guy to understand
136 what your test is for. Its highly recommended you use test names.
138 All tests are run in scalar context. So this:
140 ok( @stuff, 'I have some stuff' );
142 will do what you mean (fail if stuff is empty).
147 my($test, $name) = @_;
149 unless( $Have_Plan ) {
150 die "You tried to use ok() without a plan! Gotta have a plan.\n".
151 " use Test::Simple tests => 23; for example.\n";
156 # Make sure the print doesn't get interfered with.
159 _print *TESTERR, <<ERR if defined $name and $name !~ /\D/;
160 You named your test '$name'. You shouldn't use numbers for your test names.
165 # We must print this all in one shot or else it will break on VMS
169 $Test_Results[$Num_Tests-1] = 0;
172 $Test_Results[$Num_Tests-1] = 1;
174 $msg .= "ok $Num_Tests";
175 $msg .= " - $name" if @_ == 2;
178 _print *TESTOUT, $msg;
182 my($pack, $file, $line) = (caller)[0,1,2];
183 if( $pack eq 'Test::More' ) {
184 ($file, $line) = (caller(1))[1,2];
186 _print *TESTERR, "# Failed test ($file at line $line)\n";
194 Test::Simple will start by printing number of tests run in the form
195 "1..M" (so "1..5" means you're going to run 5 tests). This strange
196 format lets Test::Harness know how many tests you plan on running in
197 case something goes horribly wrong.
199 If all your tests passed, Test::Simple will exit with zero (which is
200 normal). If anything failed it will exit with how many failed. If
201 you run less (or more) tests than you planned, the missing (or extras)
202 will be considered failures. If no tests were ever run Test::Simple
203 will throw a warning and exit with 255. If the test died, even after
204 having successfully completed all its tests, it will still be
205 considered a failure and will exit with 255.
207 So the exit codes are...
209 0 all tests successful
211 any other number how many failed (including missing or extras)
213 If you fail more than 254 tests, it will be reported as 254.
219 =item B<_sanity_check>
223 Runs a bunch of end of test sanity checks to make sure reality came
224 through ok. If anything is wrong it will die with a fairly friendly
231 _whoa($Num_Tests < 0, 'Says here you ran a negative number of tests!');
232 _whoa(!$Have_Plan and $Num_Tests,
233 'Somehow your tests ran without a plan!');
234 _whoa($Num_Tests != @Test_Results,
235 'Somehow you got a different number of results than tests ran!');
240 _whoa($check, $description);
242 A sanity check, similar to assert(). If the $check is true, something
243 has gone horribly wrong. It will die with the given $description and
244 a note to contact the author.
249 my($check, $desc) = @_;
253 This should never happen! Please contact the author immediately!
262 Perl seems to have some trouble with exiting inside an END block. 5.005_03
263 and 5.6.1 both seem to do odd things. Instead, this function edits $?
264 directly. It should ONLY be called from inside an END block. It
265 doesn't actually exit, that's your job.
281 $SIG{__DIE__} = sub {
282 # We don't want to muck with death in an eval, but $^S isn't
283 # totally reliable. 5.005_03 and 5.6.1 both do the wrong thing
284 # with it. Instead, we use caller. This also means it runs under
287 for( my $stack = 1; my $sub = (caller($stack))[3]; $stack++ ) {
288 $in_eval = 1 if $sub =~ /^\(eval\)/;
290 $Test_Died = 1 unless $in_eval;
296 # Bailout if import() was never called. This is so
297 # "require Test::Simple" doesn't puke.
298 do{ _my_exit(0) && return } if !$Have_Plan and !$Num_Tests;
300 # Figure out if we passed or failed and print helpful messages.
302 # The plan? We have no plan.
303 unless( $Planned_Tests ) {
304 _print *TESTOUT, "1..$Num_Tests\n";
305 $Planned_Tests = $Num_Tests;
308 my $num_failed = grep !$_, @Test_Results[0..$Planned_Tests-1];
309 $num_failed += abs($Planned_Tests - @Test_Results);
311 if( $Num_Tests < $Planned_Tests ) {
312 _print *TESTERR, <<"FAIL";
313 # Looks like you planned $Planned_Tests tests but only ran $Num_Tests.
316 elsif( $Num_Tests > $Planned_Tests ) {
317 my $num_extra = $Num_Tests - $Planned_Tests;
318 _print *TESTERR, <<"FAIL";
319 # Looks like you planned $Planned_Tests tests but ran $num_extra extra.
322 elsif ( $num_failed ) {
323 _print *TESTERR, <<"FAIL";
324 # Looks like you failed $num_failed tests of $Planned_Tests.
329 _print *TESTERR, <<"FAIL";
330 # Looks like your test died just after $Num_Tests.
333 _my_exit( 255 ) && return;
336 _my_exit( $num_failed <= 254 ? $num_failed : 254 ) && return;
338 elsif ( $Test::Simple::Skip_All ) {
339 _my_exit( 0 ) && return;
342 _print *TESTERR, "# No tests run!\n";
343 _my_exit( 255 ) && return;
350 This module is by no means trying to be a complete testing system.
351 Its just to get you started. Once you're off the ground its
352 recommended you look at L<Test::More>.
357 Here's an example of a simple .t file for the fictional Film module.
359 use Test::Simple tests => 5;
361 use Film; # What you're testing.
363 my $btaste = Film->new({ Title => 'Bad Taste',
364 Director => 'Peter Jackson',
366 NumExplodingSheep => 1
368 ok( defined($btaste) and ref $btaste eq 'Film', 'new() works' );
370 ok( $btaste->Title eq 'Bad Taste', 'Title() get' );
371 ok( $btsate->Director eq 'Peter Jackson', 'Director() get' );
372 ok( $btaste->Rating eq 'R', 'Rating() get' );
373 ok( $btaste->NumExplodingSheep == 1, 'NumExplodingSheep() get' );
375 It will produce output like this:
380 ok 3 - Director() get
381 not ok 4 - Rating() get
382 ok 5 - NumExplodingSheep() get
384 Indicating the Film::Rating() method is broken.
389 Test::Simple will only report a maximum of 254 failures in its exit
390 code. If this is a problem, you probably have a huge test script.
391 Split it into multiple files. (Otherwise blame the Unix folks for
392 using an unsigned short integer as the exit status).
397 This module was conceived while talking with Tony Bowden in his
398 kitchen one night about the problems I was having writing some really
399 complicated feature into the new Testing module. He observed that the
400 main problem is not dealing with these edge cases but that people hate
401 to write tests B<at all>. What was needed was a dead simple module
402 that took all the hard work out of testing and was really, really easy
403 to learn. Paul Johnson simultaneously had this idea (unfortunately,
404 he wasn't in Tony's kitchen). This is it.
409 Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern
410 <schwern@pobox.com>, wardrobe by Calvin Klein.
419 More testing functions! Once you outgrow Test::Simple, look at
420 Test::More. Test::Simple is 100% forward compatible with Test::More
421 (ie. you can just use Test::More instead of Test::Simple in your
422 programs and things will still work).
426 The original Perl testing module.
430 Elaborate unit testing.
432 =item L<Pod::Tests>, L<SelfTest>
434 Embed tests in your code!
436 =item L<Test::Harness>
438 Interprets the output of your test program.