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

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

cpanm Test::Simple

perl -MCPAN -e shell
install Test::Simple