NAME
Test::Builder::Provider - Helper for writing testing tools
TEST COMPONENT MAP
[Test Script] > [Test Tool] > [Test::Builder] > [Test::Bulder::Stream] > [Result Formatter]
^
You are here
A test script uses a test tool such as Test::More, which uses Test::Builder to produce results. The results are sent to Test::Builder::Stream which then forwards them on to one or more formatters. The default formatter is Test::Builder::Fromatter::TAP which produces TAP output.
DESCRIPTION
This package provides you with tools to write testing tools. It makes your job of integrating with Test::Builder and other testing tools much easier.
SYNOPSYS
Instead of use Exporter or other exporters, you can use convenience functions to define exports on the fly.
package My::Tester
use strict;
use warnings;
use Test::Builder::Provider;
sub before_import {
my $class = shift;
my ($import_args_ref) = @_;
... Modify $import_args_ref ...
# $import_args_ref should contain only what you want to pass as
# arguments into export().
}
sub after_import {
my $class = shift;
my @args = @_;
...
}
# Provide (export) an 'ok' function (the anonymous function is the export)
provide ok => sub { builder()->ok(@_) };
# Provide some of our package functions as test functions.
provides qw/is is_deeply/;
sub is { ... }
sub is_deeply { ... };
# Provide a 'subtests' function. Functions that accept a block like this
# that may run other tests should be use provide_nest to mark them as
# nested providers.
provide_nest subtests => sub(&) { ... };
# Provide a couple nested functions defined in our package
provide_nests qw/subtests_alt subtests_xxx/;
sub subtests_alt(&) { ... }
sub subtests_xxx(&) { ... }
# Export a helper function that does not produce any results (regular
# export).
give echo => sub { print @_ };
# Same for multiple functions in our package:
gives qw/echo_stdout echo_stderr/;
sub echo_stdout { ... }
sub echo_stderr { ... }
IN A TEST FILE
use Test::More;
use My::Tester;
ok(1, "blah");
is(1, 1, "got 1");
subtests {
ok(1, "a subtest");
ok(1, "another");
};
USING EXTERNAL EXPORT LIBRARIES
Maybe you like Exporter or another export tool. In that case you still need the 'provides' and 'provide_nests' functions from here to mark testing tools as such.
This is also a quick way to update an old library, but you also need to remove any references to $Test::Builder::Level
which is now deprecated.
package My::Tester
use strict;
use warnings;
use base 'Exporter';
use Test::Builder::Provider qw/provides provide_nests/;
our @EXPORT = qw{
ok is is_deeply
subtests subtests_alt subtests_xxx
echo echo_stderr echo stdout
};
# *mark* the testing tools
provides qw/ok is is_deeply/;
sub ok { builder()->ok(@_) }
sub is { ... }
sub is_deeply { ... };
# *mark* the nesting test tools
provide_nests qw/subtests subtests_alt subtests_xxx/;
sub subtests(&) { ... }
sub subtests_alt(&) { ... }
sub subtests_xxx(&) { ... }
# No special marking needed for these as they do not produce results.
sub echo { print @_ }
sub echo_stdout { ... }
sub echo_stderr { ... }
SUPPORTING OLD VERSIONS
See Test::Builder::Compat which is a seperate dist that has no dependancies. You can use it to write providers that make use of the new Test::Builder, while also working fine on older versions of Test::Builder.
META-DATA
Importing this module will always mark your package as a test provider. It does this by injecting a method into your package called 'TB_PROVIDER_META'. This method simply returns the meta-data hash for your package.
To avoid this you can use 'require' instead of 'use', or you can use () in your import:
# Load the module, but do not make this package a provider.
require Test::Builder::Provider;
use Test::Builder::Provider();
EXPORTS
All of these subs are injected into your package (unless you request a subset).
- my $tb = TB()
- my $tb = builder()
-
Get the correct instance of Test::Builder. Usually this is the instance used in the test file calling a tool in your package. If no such instance can be found the default Test::Builder instance will be used.
- $class->anoint($target)
-
Used to mark the $target package as a test package that consumes your test package for tools. This is done automatically for you if you use the default 'import' sub below.
- $class->import()
- $class->import(@list)
-
An import() function that exports your tools to any consumers of your class.
- $class->export($dest)
- $class->export($dest, @list)
-
Export the packages tools into the $dest package. @list me be specified to restrict what is exported. Prefix any item in the list with '!' to prevent exporting it.
- provide $name
- provide $name => sub { ... }
-
Provide a testing tool that will produce results. If no coderef is given it will look for a coderef with $name in your package.
You may also use this to export refs of any type.
- provides qw/sub1 sub2 .../
-
Like provide except you can specify multiple subs to export.
- provide_nest $name
- provide_nest $name => sub(&) { ... }
-
Like provide, but use on tools like subtests that accept a block of tests to be run.
- provide_nests qw/sub1 sub2 .../
-
Same as providesm, but used on nesting tools.
- give $name
- give $name => sub { ... }
-
Export a helper function that does not produce results.
- gives qw/sub1 sub2 .../
-
Export helper functions.
HOW DO I TEST MY TEST TOOLS?
See Test::Tester2
AUTHORS
SOURCE
The source code repository for Test::More can be found at http://github.com/Test-More/test-more/.
COPYRIGHT
Copyright 2014 Chad Granum <exodist7@gmail.com>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html