require Exporter;
use vars qw($VERSION @ISA @EXPORT %EXPORT_TAGS $TODO);
-$VERSION = '0.41';
+$VERSION = '0.47';
@ISA = qw(Exporter);
@EXPORT = qw(ok use_ok require_ok
is isnt like unlike is_deeply
my $caller = caller;
$Test->exported_to($caller);
- $Test->plan(@plan);
my @imports = ();
foreach my $idx (0..$#plan) {
if( $plan[$idx] eq 'import' ) {
- @imports = @{$plan[$idx+1]};
+ my($tag, $imports) = splice @plan, $idx, 2;
+ @imports = @$imports;
last;
}
}
+ $Test->plan(@plan);
+
__PACKAGE__->_export_to_level(1, __PACKAGE__, @imports);
}
=head2 Test names
By convention, each test is assigned a number in order. This is
-largely done automatically for you. However, its often very useful to
+largely done automatically for you. However, it's often very useful to
assign a name to each test. Which would you rather see:
ok 4
to find the test in your script, simply search for "simple
exponential".
-All test functions take a name argument. Its optional, but highly
+All test functions take a name argument. It's optional, but highly
suggested that you use it.
Will produce something like this:
not ok 17 - Is foo the same as bar?
- # Failed test 1 (foo.t at line 139)
+ # Failed test (foo.t at line 139)
# got: 'waffle'
# expected: 'yarblokos'
# &&
# undef
-Its also useful in those cases where you are comparing numbers and
+It's also useful in those cases where you are comparing numbers and
is()'s use of C<eq> will interfere:
cmp_ok( $big_hairy_number, '==', $another_big_hairy_number );
sub can_ok ($@) {
my($proto, @methods) = @_;
- my $class= ref $proto || $proto;
+ my $class = ref $proto || $proto;
unless( @methods ) {
my $ok = $Test->ok( 0, "$class->can(...)" );
my @nok = ();
foreach my $method (@methods) {
- my $test = "'$class'->can('$method')";
local($!, $@); # don't interfere with caller's $@
# eval sometimes resets $!
- eval $test || push @nok, $method;
+ eval { $proto->can($method) } || push @nok, $method;
}
my $name;
- $name = @methods == 1 ? "$class->can($methods[0])"
+ $name = @methods == 1 ? "$class->can('$methods[0]')"
: "$class->can(...)";
my $ok = $Test->ok( !@nok, $name );
if( $@ =~ /^Can't call method "isa" on unblessed reference/ ) {
if( !UNIVERSAL::isa($object, $class) ) {
my $ref = ref $object;
- $diag = "$obj_name isn't a '$class' its a '$ref'";
+ $diag = "$obj_name isn't a '$class' it's a '$ref'";
}
} else {
die <<WHOA;
}
elsif( !$rslt ) {
my $ref = ref $object;
- $diag = "$obj_name isn't a '$class' its a '$ref'";
+ $diag = "$obj_name isn't a '$class' it's a '$ref'";
}
}
BEGIN { use_ok($module, @imports); }
These simply use the given $module and test to make sure the load
-happened ok. Its recommended that you run use_ok() inside a BEGIN
+happened ok. It's recommended that you run use_ok() inside a BEGIN
block so its functions are exported at compile-time and prototypes are
properly honored.
use Some::Module qw(foo bar);
+don't try to do this:
+
+ BEGIN {
+ use_ok('Some::Module');
+
+ ...some code that depends on the use...
+ ...happening at compile time...
+ }
+
+instead, you want:
+
+ BEGIN { use_ok('Some::Module') }
+ BEGIN { ...some code that depends on the use... }
+
=cut
eval <<USE;
package $pack;
require $module;
-$module->import(\@imports);
+'$module'->import(\@imports);
USE
my $ok = $Test->ok( !$@, "use $module;" );
...normal testing code goes here...
}
-This declares a block of tests to skip, $how_many tests there are,
-$why and under what $condition to skip them. An example is the
-easiest way to illustrate:
+This declares a block of tests that might be skipped, $how_many tests
+there are, $why and under what $condition to skip them. An example is
+the easiest way to illustrate:
SKIP: {
- skip "Pigs don't fly here", 2 unless Pigs->can('fly');
+ eval { require HTML::Lint };
- my $pig = Pigs->new;
- $pig->takeoff;
+ skip "HTML::Lint not installed", 2 if $@;
- ok( $pig->altitude > 0, 'Pig is airborne' );
- ok( $pig->airspeed > 0, ' and moving' );
- }
+ my $lint = new HTML::Lint;
+ isa_ok( $lint, "HTML::Lint" );
-If pigs cannot fly, the whole block of tests will be skipped
-completely. Test::More will output special ok's which Test::Harness
-interprets as skipped tests. Its important to include $how_many tests
-are in the block so the total number of tests comes out right (unless
-you're using C<no_plan>, in which case you can leave $how_many off if
-you like).
+ $lint->parse( $html );
+ is( $lint->errors, 0, "No errors found in HTML" );
+ }
-Its perfectly safe to nest SKIP blocks.
+If the user does not have HTML::Lint installed, the whole block of
+code I<won't be run at all>. Test::More will output special ok's
+which Test::Harness interprets as skipped, but passing, tests.
+It's important that $how_many accurately reflects the number of tests
+in the SKIP block so the # of tests run will match up with your plan.
-Tests are skipped when you B<never> expect them to B<ever> pass. Like
-an optional module is not installed or the operating system doesn't
-have some feature (like fork() or symlinks) or maybe you need an
-Internet connection and one isn't available.
+It's perfectly safe to nest SKIP blocks. Each SKIP block must have
+the label C<SKIP>, or Test::More can't work its magic.
You don't skip tests which are failing because there's a bug in your
-program. For that you use TODO. Read on.
-
-
-=for _Future
-See L</Why are skip and todo so weird?>
+program, or for which you don't yet have code written. For that you
+use TODO. Read on.
=cut
will run the tests normally, but print out special flags indicating
they are "todo". Test::Harness will interpret failures as being ok.
Should anything succeed, it will report it as an unexpected success.
+You then know the thing you had todo is done and can remove the
+TODO flag.
The nice part about todo tests, as opposed to simply commenting out a
block of tests, is it's like having a programmatic todo list. You know
...normal testing code...
}
-With todo tests, its best to have the tests actually run. That way
+With todo tests, it's best to have the tests actually run. That way
you'll know when they start passing. Sometimes this isn't possible.
Often a failing test will cause the whole program to die or hang, even
inside an C<eval BLOCK> with and using C<alarm>. In these extreme
last TODO;
}
+=item When do I use SKIP vs. TODO?
+
+B<If it's something the user might not be able to do>, use SKIP.
+This includes optional modules that aren't installed, running under
+an OS that doesn't have some feature (like fork() or symlinks), or maybe
+you need an Internet connection and one isn't available.
+
+B<If it's something the programmer hasn't done yet>, use TODO. This
+is for any code you haven't written yet, or bugs you have yet to fix,
+but want to put tests in your testing script (always a good idea).
+
=back
important. This is a deep check, but the irrelevancy of order only
applies to the top level.
+B<NOTE> By historical accident, this is not a true set comparision.
+While the order of elements does not matter, duplicate elements do.
+
=cut
# We must make sure that references are treated neutrally. It really
Test::More is B<explicitly> tested all the way back to perl 5.004.
+Test::More is thread-safe for perl 5.8.0 and up.
+
=head1 BUGS and CAVEATS
=over 4
=head1 SEE ALSO
L<Test::Simple> if all this confuses you and you just want to write
-some tests. You can upgrade to Test::More later (its forward
+some tests. You can upgrade to Test::More later (it's forward
compatible).
L<Test::Differences> for more ways to test complex data structures.