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