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;
|
---|