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