1*0Sstevel@tonic-gatepackage Test::Simple; 2*0Sstevel@tonic-gate 3*0Sstevel@tonic-gateuse 5.004; 4*0Sstevel@tonic-gate 5*0Sstevel@tonic-gateuse strict 'vars'; 6*0Sstevel@tonic-gateuse vars qw($VERSION); 7*0Sstevel@tonic-gate$VERSION = '0.47'; 8*0Sstevel@tonic-gate 9*0Sstevel@tonic-gate 10*0Sstevel@tonic-gateuse Test::Builder; 11*0Sstevel@tonic-gatemy $Test = Test::Builder->new; 12*0Sstevel@tonic-gate 13*0Sstevel@tonic-gatesub import { 14*0Sstevel@tonic-gate my $self = shift; 15*0Sstevel@tonic-gate my $caller = caller; 16*0Sstevel@tonic-gate *{$caller.'::ok'} = \&ok; 17*0Sstevel@tonic-gate 18*0Sstevel@tonic-gate $Test->exported_to($caller); 19*0Sstevel@tonic-gate $Test->plan(@_); 20*0Sstevel@tonic-gate} 21*0Sstevel@tonic-gate 22*0Sstevel@tonic-gate 23*0Sstevel@tonic-gate=head1 NAME 24*0Sstevel@tonic-gate 25*0Sstevel@tonic-gateTest::Simple - Basic utilities for writing tests. 26*0Sstevel@tonic-gate 27*0Sstevel@tonic-gate=head1 SYNOPSIS 28*0Sstevel@tonic-gate 29*0Sstevel@tonic-gate use Test::Simple tests => 1; 30*0Sstevel@tonic-gate 31*0Sstevel@tonic-gate ok( $foo eq $bar, 'foo is bar' ); 32*0Sstevel@tonic-gate 33*0Sstevel@tonic-gate 34*0Sstevel@tonic-gate=head1 DESCRIPTION 35*0Sstevel@tonic-gate 36*0Sstevel@tonic-gate** If you are unfamiliar with testing B<read Test::Tutorial> first! ** 37*0Sstevel@tonic-gate 38*0Sstevel@tonic-gateThis is an extremely simple, extremely basic module for writing tests 39*0Sstevel@tonic-gatesuitable for CPAN modules and other pursuits. If you wish to do more 40*0Sstevel@tonic-gatecomplicated testing, use the Test::More module (a drop-in replacement 41*0Sstevel@tonic-gatefor this one). 42*0Sstevel@tonic-gate 43*0Sstevel@tonic-gateThe basic unit of Perl testing is the ok. For each thing you want to 44*0Sstevel@tonic-gatetest your program will print out an "ok" or "not ok" to indicate pass 45*0Sstevel@tonic-gateor fail. You do this with the ok() function (see below). 46*0Sstevel@tonic-gate 47*0Sstevel@tonic-gateThe only other constraint is you must pre-declare how many tests you 48*0Sstevel@tonic-gateplan to run. This is in case something goes horribly wrong during the 49*0Sstevel@tonic-gatetest and your test program aborts, or skips a test or whatever. You 50*0Sstevel@tonic-gatedo this like so: 51*0Sstevel@tonic-gate 52*0Sstevel@tonic-gate use Test::Simple tests => 23; 53*0Sstevel@tonic-gate 54*0Sstevel@tonic-gateYou must have a plan. 55*0Sstevel@tonic-gate 56*0Sstevel@tonic-gate 57*0Sstevel@tonic-gate=over 4 58*0Sstevel@tonic-gate 59*0Sstevel@tonic-gate=item B<ok> 60*0Sstevel@tonic-gate 61*0Sstevel@tonic-gate ok( $foo eq $bar, $name ); 62*0Sstevel@tonic-gate ok( $foo eq $bar ); 63*0Sstevel@tonic-gate 64*0Sstevel@tonic-gateok() is given an expression (in this case C<$foo eq $bar>). If it's 65*0Sstevel@tonic-gatetrue, the test passed. If it's false, it didn't. That's about it. 66*0Sstevel@tonic-gate 67*0Sstevel@tonic-gateok() prints out either "ok" or "not ok" along with a test number (it 68*0Sstevel@tonic-gatekeeps track of that for you). 69*0Sstevel@tonic-gate 70*0Sstevel@tonic-gate # This produces "ok 1 - Hell not yet frozen over" (or not ok) 71*0Sstevel@tonic-gate ok( get_temperature($hell) > 0, 'Hell not yet frozen over' ); 72*0Sstevel@tonic-gate 73*0Sstevel@tonic-gateIf you provide a $name, that will be printed along with the "ok/not 74*0Sstevel@tonic-gateok" to make it easier to find your test when if fails (just search for 75*0Sstevel@tonic-gatethe name). It also makes it easier for the next guy to understand 76*0Sstevel@tonic-gatewhat your test is for. It's highly recommended you use test names. 77*0Sstevel@tonic-gate 78*0Sstevel@tonic-gateAll tests are run in scalar context. So this: 79*0Sstevel@tonic-gate 80*0Sstevel@tonic-gate ok( @stuff, 'I have some stuff' ); 81*0Sstevel@tonic-gate 82*0Sstevel@tonic-gatewill do what you mean (fail if stuff is empty) 83*0Sstevel@tonic-gate 84*0Sstevel@tonic-gate=cut 85*0Sstevel@tonic-gate 86*0Sstevel@tonic-gatesub ok ($;$) { 87*0Sstevel@tonic-gate $Test->ok(@_); 88*0Sstevel@tonic-gate} 89*0Sstevel@tonic-gate 90*0Sstevel@tonic-gate 91*0Sstevel@tonic-gate=back 92*0Sstevel@tonic-gate 93*0Sstevel@tonic-gateTest::Simple will start by printing number of tests run in the form 94*0Sstevel@tonic-gate"1..M" (so "1..5" means you're going to run 5 tests). This strange 95*0Sstevel@tonic-gateformat lets Test::Harness know how many tests you plan on running in 96*0Sstevel@tonic-gatecase something goes horribly wrong. 97*0Sstevel@tonic-gate 98*0Sstevel@tonic-gateIf all your tests passed, Test::Simple will exit with zero (which is 99*0Sstevel@tonic-gatenormal). If anything failed it will exit with how many failed. If 100*0Sstevel@tonic-gateyou run less (or more) tests than you planned, the missing (or extras) 101*0Sstevel@tonic-gatewill be considered failures. If no tests were ever run Test::Simple 102*0Sstevel@tonic-gatewill throw a warning and exit with 255. If the test died, even after 103*0Sstevel@tonic-gatehaving successfully completed all its tests, it will still be 104*0Sstevel@tonic-gateconsidered a failure and will exit with 255. 105*0Sstevel@tonic-gate 106*0Sstevel@tonic-gateSo the exit codes are... 107*0Sstevel@tonic-gate 108*0Sstevel@tonic-gate 0 all tests successful 109*0Sstevel@tonic-gate 255 test died 110*0Sstevel@tonic-gate any other number how many failed (including missing or extras) 111*0Sstevel@tonic-gate 112*0Sstevel@tonic-gateIf you fail more than 254 tests, it will be reported as 254. 113*0Sstevel@tonic-gate 114*0Sstevel@tonic-gateThis module is by no means trying to be a complete testing system. 115*0Sstevel@tonic-gateIt's just to get you started. Once you're off the ground its 116*0Sstevel@tonic-gaterecommended you look at L<Test::More>. 117*0Sstevel@tonic-gate 118*0Sstevel@tonic-gate 119*0Sstevel@tonic-gate=head1 EXAMPLE 120*0Sstevel@tonic-gate 121*0Sstevel@tonic-gateHere's an example of a simple .t file for the fictional Film module. 122*0Sstevel@tonic-gate 123*0Sstevel@tonic-gate use Test::Simple tests => 5; 124*0Sstevel@tonic-gate 125*0Sstevel@tonic-gate use Film; # What you're testing. 126*0Sstevel@tonic-gate 127*0Sstevel@tonic-gate my $btaste = Film->new({ Title => 'Bad Taste', 128*0Sstevel@tonic-gate Director => 'Peter Jackson', 129*0Sstevel@tonic-gate Rating => 'R', 130*0Sstevel@tonic-gate NumExplodingSheep => 1 131*0Sstevel@tonic-gate }); 132*0Sstevel@tonic-gate ok( defined($btaste) and ref $btaste eq 'Film', 'new() works' ); 133*0Sstevel@tonic-gate 134*0Sstevel@tonic-gate ok( $btaste->Title eq 'Bad Taste', 'Title() get' ); 135*0Sstevel@tonic-gate ok( $btaste->Director eq 'Peter Jackson', 'Director() get' ); 136*0Sstevel@tonic-gate ok( $btaste->Rating eq 'R', 'Rating() get' ); 137*0Sstevel@tonic-gate ok( $btaste->NumExplodingSheep == 1, 'NumExplodingSheep() get' ); 138*0Sstevel@tonic-gate 139*0Sstevel@tonic-gateIt will produce output like this: 140*0Sstevel@tonic-gate 141*0Sstevel@tonic-gate 1..5 142*0Sstevel@tonic-gate ok 1 - new() works 143*0Sstevel@tonic-gate ok 2 - Title() get 144*0Sstevel@tonic-gate ok 3 - Director() get 145*0Sstevel@tonic-gate not ok 4 - Rating() get 146*0Sstevel@tonic-gate # Failed test (t/film.t at line 14) 147*0Sstevel@tonic-gate ok 5 - NumExplodingSheep() get 148*0Sstevel@tonic-gate # Looks like you failed 1 tests of 5 149*0Sstevel@tonic-gate 150*0Sstevel@tonic-gateIndicating the Film::Rating() method is broken. 151*0Sstevel@tonic-gate 152*0Sstevel@tonic-gate 153*0Sstevel@tonic-gate=head1 CAVEATS 154*0Sstevel@tonic-gate 155*0Sstevel@tonic-gateTest::Simple will only report a maximum of 254 failures in its exit 156*0Sstevel@tonic-gatecode. If this is a problem, you probably have a huge test script. 157*0Sstevel@tonic-gateSplit it into multiple files. (Otherwise blame the Unix folks for 158*0Sstevel@tonic-gateusing an unsigned short integer as the exit status). 159*0Sstevel@tonic-gate 160*0Sstevel@tonic-gateBecause VMS's exit codes are much, much different than the rest of the 161*0Sstevel@tonic-gateuniverse, and perl does horrible mangling to them that gets in my way, 162*0Sstevel@tonic-gateit works like this on VMS. 163*0Sstevel@tonic-gate 164*0Sstevel@tonic-gate 0 SS$_NORMAL all tests successful 165*0Sstevel@tonic-gate 4 SS$_ABORT something went wrong 166*0Sstevel@tonic-gate 167*0Sstevel@tonic-gateUnfortunately, I can't differentiate any further. 168*0Sstevel@tonic-gate 169*0Sstevel@tonic-gate 170*0Sstevel@tonic-gate=head1 NOTES 171*0Sstevel@tonic-gate 172*0Sstevel@tonic-gateTest::Simple is B<explicitly> tested all the way back to perl 5.004. 173*0Sstevel@tonic-gate 174*0Sstevel@tonic-gateTest::Simple is thread-safe in perl 5.8.0 and up. 175*0Sstevel@tonic-gate 176*0Sstevel@tonic-gate=head1 HISTORY 177*0Sstevel@tonic-gate 178*0Sstevel@tonic-gateThis module was conceived while talking with Tony Bowden in his 179*0Sstevel@tonic-gatekitchen one night about the problems I was having writing some really 180*0Sstevel@tonic-gatecomplicated feature into the new Testing module. He observed that the 181*0Sstevel@tonic-gatemain problem is not dealing with these edge cases but that people hate 182*0Sstevel@tonic-gateto write tests B<at all>. What was needed was a dead simple module 183*0Sstevel@tonic-gatethat took all the hard work out of testing and was really, really easy 184*0Sstevel@tonic-gateto learn. Paul Johnson simultaneously had this idea (unfortunately, 185*0Sstevel@tonic-gatehe wasn't in Tony's kitchen). This is it. 186*0Sstevel@tonic-gate 187*0Sstevel@tonic-gate 188*0Sstevel@tonic-gate=head1 SEE ALSO 189*0Sstevel@tonic-gate 190*0Sstevel@tonic-gate=over 4 191*0Sstevel@tonic-gate 192*0Sstevel@tonic-gate=item L<Test::More> 193*0Sstevel@tonic-gate 194*0Sstevel@tonic-gateMore testing functions! Once you outgrow Test::Simple, look at 195*0Sstevel@tonic-gateTest::More. Test::Simple is 100% forward compatible with Test::More 196*0Sstevel@tonic-gate(i.e. you can just use Test::More instead of Test::Simple in your 197*0Sstevel@tonic-gateprograms and things will still work). 198*0Sstevel@tonic-gate 199*0Sstevel@tonic-gate=item L<Test> 200*0Sstevel@tonic-gate 201*0Sstevel@tonic-gateThe original Perl testing module. 202*0Sstevel@tonic-gate 203*0Sstevel@tonic-gate=item L<Test::Unit> 204*0Sstevel@tonic-gate 205*0Sstevel@tonic-gateElaborate unit testing. 206*0Sstevel@tonic-gate 207*0Sstevel@tonic-gate=item L<Test::Inline>, L<SelfTest> 208*0Sstevel@tonic-gate 209*0Sstevel@tonic-gateEmbed tests in your code! 210*0Sstevel@tonic-gate 211*0Sstevel@tonic-gate=item L<Test::Harness> 212*0Sstevel@tonic-gate 213*0Sstevel@tonic-gateInterprets the output of your test program. 214*0Sstevel@tonic-gate 215*0Sstevel@tonic-gate=back 216*0Sstevel@tonic-gate 217*0Sstevel@tonic-gate 218*0Sstevel@tonic-gate=head1 AUTHORS 219*0Sstevel@tonic-gate 220*0Sstevel@tonic-gateIdea by Tony Bowden and Paul Johnson, code by Michael G Schwern 221*0Sstevel@tonic-gateE<lt>schwern@pobox.comE<gt>, wardrobe by Calvin Klein. 222*0Sstevel@tonic-gate 223*0Sstevel@tonic-gate 224*0Sstevel@tonic-gate=head1 COPYRIGHT 225*0Sstevel@tonic-gate 226*0Sstevel@tonic-gateCopyright 2001 by Michael G Schwern E<lt>schwern@pobox.comE<gt>. 227*0Sstevel@tonic-gate 228*0Sstevel@tonic-gateThis program is free software; you can redistribute it and/or 229*0Sstevel@tonic-gatemodify it under the same terms as Perl itself. 230*0Sstevel@tonic-gate 231*0Sstevel@tonic-gateSee F<http://www.perl.com/perl/misc/Artistic.html> 232*0Sstevel@tonic-gate 233*0Sstevel@tonic-gate=cut 234*0Sstevel@tonic-gate 235*0Sstevel@tonic-gate1; 236