| 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>schwern@pobox.comE<gt>, wardrobe by Calvin Klein. |
| 217 | |
| 218 | |
| 219 | =head1 COPYRIGHT |
| 220 | |
| 221 | Copyright 2001, 2002, 2004 by Michael G Schwern E<lt>schwern@pobox.comE<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; |