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