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