++ed by:

94 PAUSE users
66 non-PAUSE users.

Chad Granum
and 1 contributors


Test::Builder::Provider - Helper for writing testing tools


  [Test Script] > [Test Tool] > [Test::Builder] > [Test::Bulder::Stream] > [Event Formatter]
                  You are here

A test script uses a test tool such as Test::More, which uses Test::Builder to produce events. The events 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.


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.


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 nest() to run the codeblocks they
    # recieve to mark them as nested providers.
    provide subtests => sub(&) {
        my $code = shift;
        nest { $code->() };       # OR: nest(\&$code)   OR: &nest($code);

    # Provide a couple nested functions defined in our package
    provide qw/subtests_alt subtests_xxx/;
    sub subtests_alt(&) { ... }
    sub subtests_xxx(&) { ... }

    # Export a helper function that does not produce any events (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 { ... }


    use Test::More;
    use My::Tester;

    ok(1, "blah");

    is(1, 1, "got 1");

    subtests {
        ok(1, "a subtest");
        ok(1, "another");


Maybe you like Exporter or another export tool. In that case you still need the 'provides' and 'nest' 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 nest/;

    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 { ... };

    # Remember to use nest()
    provide 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 events.
    sub echo { print @_ }
    sub echo_stdout { ... }
    sub echo_stderr { ... }


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.


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();


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.


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.


An import() function that exports your tools to any consumers of your class.

$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 events. 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.

nest { ... }

Used as a tracing barrier, any events generated inside the nest will trace to the nest as opposed to the call to your provided tool.

give $name
give $name => sub { ... }

Export a helper function that does not produce events.

gives qw/sub1 sub2 .../

Export helper functions.


See Test::Tester2


Chad Granum <exodist@cpan.org>


The source code repository for Test::More can be found at http://github.com/Test-More/test-more/.


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