The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Simple-1.301001_082
River stage five • 22891 direct dependents • 32646 total dependents
190 ++
/ Test::Stream::Toolset

NAME

Test::Stream::Toolset - Helper for writing testing tools

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

    package My::Tester;
    use strict;
    use warnings;
    use Test::Stream::Toolset;

    # Optional, you can just use Exporter if you would like
    use Test::Stream::Exporter;

    # These can come from Test::More, so do not export them by default
    # exports is the Test::Stream::Exporter equivilent to @EXPORT_OK
    exports qw/context done_testing/;

    # These are the API we want to provide, export them by default
    # default_exports is the Test::Stream::Exporter equivilent to @EXPORT
    default_exports qw/my_ok my_note/;

    sub my_ok {
        my ($test, $name) = @_;
        my $ctx = context();

        my @diag;
        push @diag => "'$test' is not true!" unless $test;

        $ctx->ok($test, $name, \@diag);

        return $test ? 1 : 0; # Reduce to a boolean
    }

    sub my_note {
        my ($msg) = @_;
        my $ctx = context();

        $ctx->note($msg);

        return $msg;
    }

    sub done_testing {
        my ($expected) = @_;
        my $ctx = context();
        $ctx->done_testing($expected);
    }

    1;

TEST-MORE STYLE IMPORT

If you want to be able to pass Test-More arguments such as 'tests', 'skip_all', and 'no_plan', then use the following:

    package My::Tester;
    use Test::Stream::Exporter;               # Gives us 'import()'
    use Test::Stream::Toolset;                # default exports
    use Test::Stream::Toolset 'before_import' # Test-More style argument support

2 'use' statements were used above for clarity, you can get all the desired imports at once:

    use Test::Stream::Toolset qw/context init_tester is_tester before_import/;

Then in the test:

    use My::Tester tests => 5;

EXPORTS

$ctx = context()

The context() method is used to get the current context, generating one if necessary. The context object is an instance of Test::Stream::Context, and is used to generate events suck as ok and plan. The context also knows what file+line errors should be reported at.

WARNING: Do not directly store the context in anything other than a lexical variable scoped to your function! As long as there are references to a context object, context() will return that object. You want the object to be destroyed at the end of the current scope so that the next function you call can create a new one. If you need a copy of the context use $ctx = $ctx->snapshot.

$meta = init_tester($CLASS)

This method can be used to initialize a class as a test class. In most cases you do not actually need to use this. If the class is already a tester this will return the existing meta object.

$meta = is_tester($CLASS)

This method can be used to check if an object is a tester. If the object is a tester it will return the meta object for the tester.

before_import

This method is used by import() to parse Test-More style import arguments. You should never need to run this yourself, it works just by being imported.

NOTE: This will only work if you use Test::Stream::Exporter for your 'import' method.

GENERATING EVENTS

Events are always generated via a context object. Whenever you load an Test::Stream::Event class it will add a method to Test::Stream::Context which can be used to fire off that type of event.

The following event types are all loaded automatically by Test::Stream::Toolset

Test::Stream::Event::Ok
    $ctx->ok($bool, $name, \@diag)

Ok events are your actual assertions. You assert that a condition is what you expect. It is recommended that you name your assertions. You can include an array of diag objects and/or diagniostics strings that will be printed to STDERR as comments in the event of a failure.

Test::Stream::Event::Diag
    $ctx->diag($MESSAGE)

Produce an independant diagnostics message.

Test::Stream::Event::Note
    $ctx->note($MESSAGE)

Produce a note, that is a message that is printed to STDOUT as a comment.

Test::Stream::Event::Plan
    $ctx->plan($MAX, $DIRECTIVE, $REASON)

This will set the plan. $MAX should be the number of tests you expect to run. You may set this to 0 for some plan directives. Examples of directives are 'skip_all' and 'no_plan'. Some directives have an additional argument called $REASON which is aptly named as the reason for the directive.

Test::Stream::Event::Bail
    $ctx->bail($MESSAGE)

In the event of a catostrophic failure that should terminate the test file, use this event to stop everything and print the reason.

Test::Stream::Event::Finish
Test::Stream::Event::Child
Test::Stream::Event::Subtest

These are not intended for public use, but are documented for completeness.

MODIFYING EVENTS

If you want to make changes to event objects before they are processed, you can add a munger. The return from a munger is ignored, you must make your changes directly to the event object.

    Test::Stream->shared->munge(sub {
        my ($stream, $event) = @_;
        ...
    });

Note: every munger is called for every event of every type. There is also no way to remove a munger. For performance reasons it is best to only ever add one munger per toolset which dispatches according to events and state.

LISTENING FOR EVENTS

If you wish to know when an event has occured so that you can do something after it has been processed, you can add a listener. Your listener will be called for every single event that occurs, after it has been processed. The return from a listener is ignored.

    Test::Stream->shared->listen(sub {
        my ($stream, $event) = @_;
        ...
    });

Note: every listener is called for every event of every type. There is also no way to remove a listener. For performance reasons it is best to only ever add one listener per toolset which dispatches according to events and state.

I WANT TO EMBED FUNCTIONALITY FROM TEST::MORE

Take a look at Test::More::Tools which provides an interfaces to the code in Test::More. You can use that library to produce booleans and diagnostics without actually triggering events, giving you the opportunity to generate your own.

FROM TEST::BUILDER TO TEST::STREAM

This is a list of things people used to override in Test::Builder, and the new API that should be used instead of overrides.

ok
note
diag
plan

In the past people would override these methods on Test::Builder. Test::Stream now provides a proper API for handling all event types.

Anything that used to be done via overrides can now be done using c<Test::Stream->shared->listen(sub { ... })> and Test::Stream-shared->munge(sub { ... })>, which are documented above.

done_testing

In the past people have overriden done_testing() to insert some code between the last test and the final plan. The proper way to do this now is with a follow_up hook.

    Test::Stream->shared->follow_up(sub {
        my ($context) = @_;
        ...
    });

There are multiple ways that follow_ups will be triggered, but they are guarenteed to only be called once, at the end of testing. This will either be the start of done_testing(), or an END block called after your tests are complete.

HOW DO I TEST MY TEST TOOLS?

See Test::Stream::Tester. This library gives you all the tools you need to test your testing tools.

SOURCE

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

MAINTAINER

Chad Granum <exodist@cpan.org>

AUTHORS

The following people have all contributed to the Test-More dist (sorted using VIM's sort function).

Chad Granum <exodist@cpan.org>
Fergal Daly <fergal@esatclear.ie>>
Mark Fowler <mark@twoshortplanks.com>
Michael G Schwern <schwern@pobox.com>
唐鳳

COPYRIGHT

There has been a lot of code migration between modules, here are all the original copyrights together:

Test::Stream
Test::Stream::Tester

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

Test::Simple
Test::More
Test::Builder

Originally authored by Michael G Schwern <schwern@pobox.com> with much inspiration from Joshua Pritikin's Test module and lots of help from Barrie Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa gang.

Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern <schwern@pobox.com>, wardrobe by Calvin Klein.

Copyright 2001-2008 by Michael G Schwern <schwern@pobox.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

Test::use::ok

To the extent possible under law, 唐鳳 has waived all copyright and related or neighboring rights to Test-use-ok.

This work is published from Taiwan.

http://creativecommons.org/publicdomain/zero/1.0

Test::Tester

This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some parts are based on other people's work.

Under the same license as Perl itself

See http://www.perl.com/perl/misc/Artistic.html

Test::Builder::Tester

Copyright Mark Fowler <mark@twoshortplanks.com> 2002, 2004.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.