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