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

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

nest { ... }

nest(\&$code)

&nest($code)

Used as a tracing barrier, any results 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 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