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

Chad Granum <exodist@cpan.org>

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