++ed by:
82 non-PAUSE users
Author image Chad Granum
and 1 contributors


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


  [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.


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


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


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


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