|
Packit |
d03632 |
package Test::Simple;
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
use 5.004;
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
use strict 'vars';
|
|
Packit |
d03632 |
our ($VERSION);
|
|
Packit |
d03632 |
$VERSION = '0.60';
|
|
Packit |
d03632 |
$VERSION = eval $VERSION; # make the alpha version come out as a number
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
use Test::Builder;
|
|
Packit |
d03632 |
my $Test = Test::Builder->new;
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
sub import {
|
|
Packit |
d03632 |
my $self = shift;
|
|
Packit |
d03632 |
my $caller = caller;
|
|
Packit |
d03632 |
*{$caller.'::ok'} = \&ok;
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
$Test->exported_to($caller);
|
|
Packit |
d03632 |
$Test->plan(@_);
|
|
Packit |
d03632 |
}
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 NAME
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Test::Simple - Basic utilities for writing tests.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 SYNOPSIS
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
use Test::Simple tests => 1;
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
ok( $foo eq $bar, 'foo is bar' );
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 DESCRIPTION
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
** If you are unfamiliar with testing B<read Test::Tutorial> first! **
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
This is an extremely simple, extremely basic module for writing tests
|
|
Packit |
d03632 |
suitable for CPAN modules and other pursuits. If you wish to do more
|
|
Packit |
d03632 |
complicated testing, use the Test::More module (a drop-in replacement
|
|
Packit |
d03632 |
for this one).
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
The basic unit of Perl testing is the ok. For each thing you want to
|
|
Packit |
d03632 |
test your program will print out an "ok" or "not ok" to indicate pass
|
|
Packit |
d03632 |
or fail. You do this with the ok() function (see below).
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
The only other constraint is you must pre-declare how many tests you
|
|
Packit |
d03632 |
plan to run. This is in case something goes horribly wrong during the
|
|
Packit |
d03632 |
test and your test program aborts, or skips a test or whatever. You
|
|
Packit |
d03632 |
do this like so:
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
use Test::Simple tests => 23;
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
You must have a plan.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=over 4
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=item B<ok>
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
ok( $foo eq $bar, $name );
|
|
Packit |
d03632 |
ok( $foo eq $bar );
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
ok() is given an expression (in this case C<$foo eq $bar>). If it's
|
|
Packit |
d03632 |
true, the test passed. If it's false, it didn't. That's about it.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
ok() prints out either "ok" or "not ok" along with a test number (it
|
|
Packit |
d03632 |
keeps track of that for you).
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
# This produces "ok 1 - Hell not yet frozen over" (or not ok)
|
|
Packit |
d03632 |
ok( get_temperature($hell) > 0, 'Hell not yet frozen over' );
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
If you provide a $name, that will be printed along with the "ok/not
|
|
Packit |
d03632 |
ok" to make it easier to find your test when if fails (just search for
|
|
Packit |
d03632 |
the name). It also makes it easier for the next guy to understand
|
|
Packit |
d03632 |
what your test is for. It's highly recommended you use test names.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
All tests are run in scalar context. So this:
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
ok( @stuff, 'I have some stuff' );
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
will do what you mean (fail if stuff is empty)
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=cut
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
sub ok ($;$) {
|
|
Packit |
d03632 |
$Test->ok(@_);
|
|
Packit |
d03632 |
}
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=back
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Test::Simple will start by printing number of tests run in the form
|
|
Packit |
d03632 |
"1..M" (so "1..5" means you're going to run 5 tests). This strange
|
|
Packit |
d03632 |
format lets Test::Harness know how many tests you plan on running in
|
|
Packit |
d03632 |
case something goes horribly wrong.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
If all your tests passed, Test::Simple will exit with zero (which is
|
|
Packit |
d03632 |
normal). If anything failed it will exit with how many failed. If
|
|
Packit |
d03632 |
you run less (or more) tests than you planned, the missing (or extras)
|
|
Packit |
d03632 |
will be considered failures. If no tests were ever run Test::Simple
|
|
Packit |
d03632 |
will throw a warning and exit with 255. If the test died, even after
|
|
Packit |
d03632 |
having successfully completed all its tests, it will still be
|
|
Packit |
d03632 |
considered a failure and will exit with 255.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
So the exit codes are...
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
0 all tests successful
|
|
Packit |
d03632 |
255 test died
|
|
Packit |
d03632 |
any other number how many failed (including missing or extras)
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
If you fail more than 254 tests, it will be reported as 254.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
This module is by no means trying to be a complete testing system.
|
|
Packit |
d03632 |
It's just to get you started. Once you're off the ground its
|
|
Packit |
d03632 |
recommended you look at L<Test::More>.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 EXAMPLE
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Here's an example of a simple .t file for the fictional Film module.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
use Test::Simple tests => 5;
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
use Film; # What you're testing.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
my $btaste = Film->new({ Title => 'Bad Taste',
|
|
Packit |
d03632 |
Director => 'Peter Jackson',
|
|
Packit |
d03632 |
Rating => 'R',
|
|
Packit |
d03632 |
NumExplodingSheep => 1
|
|
Packit |
d03632 |
});
|
|
Packit |
d03632 |
ok( defined($btaste) && ref $btaste eq 'Film, 'new() works' );
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
ok( $btaste->Title eq 'Bad Taste', 'Title() get' );
|
|
Packit |
d03632 |
ok( $btaste->Director eq 'Peter Jackson', 'Director() get' );
|
|
Packit |
d03632 |
ok( $btaste->Rating eq 'R', 'Rating() get' );
|
|
Packit |
d03632 |
ok( $btaste->NumExplodingSheep == 1, 'NumExplodingSheep() get' );
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
It will produce output like this:
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
1..5
|
|
Packit |
d03632 |
ok 1 - new() works
|
|
Packit |
d03632 |
ok 2 - Title() get
|
|
Packit |
d03632 |
ok 3 - Director() get
|
|
Packit |
d03632 |
not ok 4 - Rating() get
|
|
Packit |
d03632 |
# Failed test (t/film.t at line 14)
|
|
Packit |
d03632 |
ok 5 - NumExplodingSheep() get
|
|
Packit |
d03632 |
# Looks like you failed 1 tests of 5
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Indicating the Film::Rating() method is broken.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 CAVEATS
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Test::Simple will only report a maximum of 254 failures in its exit
|
|
Packit |
d03632 |
code. If this is a problem, you probably have a huge test script.
|
|
Packit |
d03632 |
Split it into multiple files. (Otherwise blame the Unix folks for
|
|
Packit |
d03632 |
using an unsigned short integer as the exit status).
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Because VMS's exit codes are much, much different than the rest of the
|
|
Packit |
d03632 |
universe, and perl does horrible mangling to them that gets in my way,
|
|
Packit |
d03632 |
it works like this on VMS.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
0 SS$_NORMAL all tests successful
|
|
Packit |
d03632 |
4 SS$_ABORT something went wrong
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Unfortunately, I can't differentiate any further.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 NOTES
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Test::Simple is B<explicitly> tested all the way back to perl 5.004.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Test::Simple is thread-safe in perl 5.8.0 and up.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 HISTORY
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
This module was conceived while talking with Tony Bowden in his
|
|
Packit |
d03632 |
kitchen one night about the problems I was having writing some really
|
|
Packit |
d03632 |
complicated feature into the new Testing module. He observed that the
|
|
Packit |
d03632 |
main problem is not dealing with these edge cases but that people hate
|
|
Packit |
d03632 |
to write tests B<at all>. What was needed was a dead simple module
|
|
Packit |
d03632 |
that took all the hard work out of testing and was really, really easy
|
|
Packit |
d03632 |
to learn. Paul Johnson simultaneously had this idea (unfortunately,
|
|
Packit |
d03632 |
he wasn't in Tony's kitchen). This is it.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 SEE ALSO
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=over 4
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=item L<Test::More>
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
More testing functions! Once you outgrow Test::Simple, look at
|
|
Packit |
d03632 |
Test::More. Test::Simple is 100% forward compatible with Test::More
|
|
Packit |
d03632 |
(i.e. you can just use Test::More instead of Test::Simple in your
|
|
Packit |
d03632 |
programs and things will still work).
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=item L<Test>
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
The original Perl testing module.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=item L<Test::Unit>
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Elaborate unit testing.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=item L<Test::Inline>, L<SelfTest>
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Embed tests in your code!
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=item L<Test::Harness>
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Interprets the output of your test program.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=back
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 AUTHORS
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern
|
|
Packit |
d03632 |
E<lt>schwern@pobox.comE<gt>, wardrobe by Calvin Klein.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=head1 COPYRIGHT
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
Copyright 2001, 2002, 2004 by Michael G Schwern E<lt>schwern@pobox.comE<gt>.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
This program is free software; you can redistribute it and/or
|
|
Packit |
d03632 |
modify it under the same terms as Perl itself.
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
See F<http://www.perl.com/perl/misc/Artistic.html>
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
=cut
|
|
Packit |
d03632 |
|
|
Packit |
d03632 |
1;
|