Test::Builder - Backend for building test libraries
package My::Test::Module;
use base 'Test::Builder::Module';
my $CLASS = __PACKAGE__;
sub ok {
my($test, $name) = @_;
my $tb = $CLASS->builder;
$tb->ok($test, $name);
}Test::Simple and Test::More have proven to be popular testing modules, but they're not always flexible enough. Test::Builder provides a building block upon which to write your own test libraries which can work together.
my $Test = Test::Builder->new;Returns a Test::Builder object representing the current state of the test.
Since you only run one test per program new always returns the same Test::Builder object. No matter how many times you call new(), you're getting the same object. This is called a singleton. This is done so that multiple modules share such global information as the test counter and where test output is going.
If you want a completely new Test::Builder object different from the singleton, use create.
my $Test = Test::Builder->create;Ok, so there can be more than one Test::Builder object and this is how you get it. You might use this instead of new() if you're testing a Test::Builder based module, but otherwise you probably want new.
NOTE: the implementation is not complete. level, for example, is still shared by all Test::Builder objects, even ones created using this method. Also, the method name may change in the future.
$builder->subtest($name, \&subtests, @args);See documentation of subtest in Test::More.
subtest also, and optionally, accepts arguments which will be passed to the subtests reference.
diag $builder->name;Returns the name of the current builder. Top level builders default to $0 (the name of the executable). Child builders are named via the child method. If no name is supplied, will be named "Child of $parent->name".
$Test->reset;Reinitializes the Test::Builder singleton to its original state. Mostly useful for tests run in persistent environments where the same test might be run multiple times in the same process.
These methods are for setting up tests and declaring how many there are. You usually only want to call one of these methods.
$Test->plan('no_plan');
$Test->plan( skip_all => $reason );
$Test->plan( tests => $num_tests );A convenient way to set up your tests. Call this and Test::Builder will print the appropriate headers and take the appropriate actions.
If you call plan(), don't call any of the other methods below.
my $max = $Test->expected_tests;
$Test->expected_tests($max);Gets/sets the number of tests we expect this test to run and prints out the appropriate headers.
$Test->no_plan;Declares that this test will run an indeterminate number of tests.
$Test->done_testing();
$Test->done_testing($num_tests);Declares that you are done testing, no more tests will be run after this point.
If a plan has not yet been output, it will do so.
$num_tests is the number of tests you planned to run. If a numbered plan was already declared, and if this contradicts, a failing test will be run to reflect the planning mistake. If no_plan was declared, this will override.
If done_testing() is called twice, the second call will issue a failing test.
If $num_tests is omitted, the number of tests run will be used, like no_plan.
done_testing() is, in effect, used when you'd want to use no_plan, but safer. You'd use it like so:
$Test->ok($a == $b);
$Test->done_testing();Or to plan a variable number of tests:
for my $test (@tests) {
$Test->ok($test);
}
$Test->done_testing(scalar @tests);$plan = $Test->has_planFind out whether a plan has been defined. $plan is either undef (no plan has been set), no_plan (indeterminate # of tests) or an integer (the number of expected tests).
$Test->skip_all;
$Test->skip_all($reason);Skips all the tests, using the given $reason. Exits immediately with 0.
my $pack = $Test->exported_to;
$Test->exported_to($pack);Tells Test::Builder what package you exported your functions to.
This method isn't terribly useful since modules which share the same Test::Builder object might get exported to different packages and only the last one will be honored.
These actually run the tests, analogous to the functions in Test::More.
They all return true if the test passed, false if the test failed.
$name is always optional.
$Test->ok($test, $name);Your basic test. Pass if $test is true, fail if $test is false. Just like Test::Simple's ok().
$Test->is_eq($got, $expected, $name);Like Test::More's is(). Checks if $got eq $expected. This is the string version.
undef only ever matches another undef.
$Test->is_num($got, $expected, $name);Like Test::More's is(). Checks if $got == $expected. This is the numeric version.
undef only ever matches another undef.
$Test->isnt_eq($got, $dont_expect, $name);Like Test::More's isnt(). Checks if $got ne $dont_expect. This is the string version.
$Test->isnt_num($got, $dont_expect, $name);Like Test::More's isnt(). Checks if $got ne $dont_expect. This is the numeric version.
$Test->like($thing, qr/$regex/, $name);
$Test->like($thing, '/$regex/', $name);Like Test::More's like(). Checks if $thing matches the given $regex.
$Test->unlike($thing, qr/$regex/, $name);
$Test->unlike($thing, '/$regex/', $name);Like Test::More's unlike(). Checks if $thing does not match the given $regex.
$Test->cmp_ok($thing, $type, $that, $name);Works just like Test::More's cmp_ok().
$Test->cmp_ok($big_num, '!=', $other_big_num);These are methods which are used in the course of writing a test but are not themselves tests.
$Test->BAIL_OUT($reason);Indicates to the Test::Harness that things are going so badly all testing should terminate. This includes running any additional test scripts.
It will exit with 255.
$Test->skip;
$Test->skip($why);Skips the current test, reporting $why.
$Test->todo_skip;
$Test->todo_skip($why);Like skip(), only it will declare the test as failing and TODO. Similar to
print "not ok $tnum # TODO $why\n";These methods are useful when writing your own test methods.
$Test->maybe_regex(qr/$regex/);
$Test->maybe_regex('/$regex/');This method used to be useful back when Test::Builder worked on Perls before 5.6 which didn't have qr//. Now its pretty useless.
Convenience method for building testing functions that take regular expressions as arguments.
Takes a quoted regular expression produced by qr//, or a string representing a regular expression.
Returns a Perl value which may be used instead of the corresponding regular expression, or undef if its argument is not recognized.
For example, a version of like(), sans the useful diagnostic messages, could be written as:
sub laconic_like {
my ($self, $thing, $regex, $name) = @_;
my $usable_regex = $self->maybe_regex($regex);
die "expecting regex, found '$regex'\n"
unless $usable_regex;
$self->ok($thing =~ m/$usable_regex/, $name);
}