1package Test::Simple;
2
3use 5.004;
4
5use strict 'vars';
6use vars qw($VERSION @ISA @EXPORT);
7$VERSION = '0.62';
8$VERSION = eval $VERSION;    # make the alpha version come out as a number
9
10use Test::Builder::Module;
11@ISA    = qw(Test::Builder::Module);
12@EXPORT = qw(ok);
13
14my $CLASS = __PACKAGE__;
15
16
17=head1 NAME
18
19Test::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
32This is an extremely simple, extremely basic module for writing tests
33suitable for CPAN modules and other pursuits.  If you wish to do more
34complicated testing, use the Test::More module (a drop-in replacement
35for this one).
36
37The basic unit of Perl testing is the ok.  For each thing you want to
38test your program will print out an "ok" or "not ok" to indicate pass
39or fail.  You do this with the ok() function (see below).
40
41The only other constraint is you must pre-declare how many tests you
42plan to run.  This is in case something goes horribly wrong during the
43test and your test program aborts, or skips a test or whatever.  You
44do this like so:
45
46    use Test::Simple tests => 23;
47
48You 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
58ok() is given an expression (in this case C<$foo eq $bar>).  If it's
59true, the test passed.  If it's false, it didn't.  That's about it.
60
61ok() prints out either "ok" or "not ok" along with a test number (it
62keeps 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
67If you provide a $name, that will be printed along with the "ok/not
68ok" to make it easier to find your test when if fails (just search for
69the name).  It also makes it easier for the next guy to understand
70what your test is for.  It's highly recommended you use test names.
71
72All tests are run in scalar context.  So this:
73
74    ok( @stuff, 'I have some stuff' );
75
76will do what you mean (fail if stuff is empty)
77
78=cut
79
80sub ok ($;$) {
81    $CLASS->builder->ok(@_);
82}
83
84
85=back
86
87Test::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
89format lets Test::Harness know how many tests you plan on running in
90case something goes horribly wrong.
91
92If all your tests passed, Test::Simple will exit with zero (which is
93normal).  If anything failed it will exit with how many failed.  If
94you run less (or more) tests than you planned, the missing (or extras)
95will be considered failures.  If no tests were ever run Test::Simple
96will throw a warning and exit with 255.  If the test died, even after
97having successfully completed all its tests, it will still be
98considered a failure and will exit with 255.
99
100So 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
106If you fail more than 254 tests, it will be reported as 254.
107
108This module is by no means trying to be a complete testing system.
109It's just to get you started.  Once you're off the ground its
110recommended you look at L<Test::More>.
111
112
113=head1 EXAMPLE
114
115Here'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
133It 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
145Indicating the Film::Rating() method is broken.
146
147
148=head1 CAVEATS
149
150Test::Simple will only report a maximum of 254 failures in its exit
151code.  If this is a problem, you probably have a huge test script.
152Split it into multiple files.  (Otherwise blame the Unix folks for
153using an unsigned short integer as the exit status).
154
155Because VMS's exit codes are much, much different than the rest of the
156universe, and perl does horrible mangling to them that gets in my way,
157it works like this on VMS.
158
159    0     SS$_NORMAL        all tests successful
160    4     SS$_ABORT         something went wrong
161
162Unfortunately, I can't differentiate any further.
163
164
165=head1 NOTES
166
167Test::Simple is B<explicitly> tested all the way back to perl 5.004.
168
169Test::Simple is thread-safe in perl 5.8.0 and up.
170
171=head1 HISTORY
172
173This module was conceived while talking with Tony Bowden in his
174kitchen one night about the problems I was having writing some really
175complicated feature into the new Testing module.  He observed that the
176main problem is not dealing with these edge cases but that people hate
177to write tests B<at all>.  What was needed was a dead simple module
178that took all the hard work out of testing and was really, really easy
179to learn.  Paul Johnson simultaneously had this idea (unfortunately,
180he 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
189More testing functions!  Once you outgrow Test::Simple, look at
190Test::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
192programs and things will still work).
193
194=item L<Test>
195
196The original Perl testing module.
197
198=item L<Test::Unit>
199
200Elaborate unit testing.
201
202=item L<Test::Inline>, L<SelfTest>
203
204Embed tests in your code!
205
206=item L<Test::Harness>
207
208Interprets the output of your test program.
209
210=back
211
212
213=head1 AUTHORS
214
215Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern
216E<lt>schwern@pobox.comE<gt>, wardrobe by Calvin Klein.
217
218
219=head1 COPYRIGHT
220
221Copyright 2001, 2002, 2004 by Michael G Schwern E<lt>schwern@pobox.comE<gt>.
222
223This program is free software; you can redistribute it and/or
224modify it under the same terms as Perl itself.
225
226See F<http://www.perl.com/perl/misc/Artistic.html>
227
228=cut
229
2301;
231