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

NAME

Test::Stream - A modern infrastructure for testing.

SYNOPSYS

    # Enables modern enhancements such as forking support and TAP encoding.
    # Also turns off expensive legacy support.
    use Test::Stream;
    use Test::More;

    # ... Tests ...

    done_testing;

FEATURES

When you load Test::Stream inside your test file you activate forking support, and prevent Test::More from turning on some expensive legacy support. You will also get warnings if your code, or any other code you load uses deprecated or discouraged practices.

IMPORT ARGUMENTS

Any import argument not recognised will be treated as an export, if it is not a valid export an exception will be thrown.

'-internal'

This argument, when given first, will prevent the import process from turning on enhanced features. This is mainly for internal use (thus the name) in order to access/load Test::Stream.

subtest_tap => 'none'

Do not show events within subtests, just the subtest result itself.

subtest_tap => 'instant'

Show events as they happen (this is how legacy Test::More worked). This is the default.

subtest_tap => 'delayed'

Show events within subtest AFTER the subtest event itself is complete.

subtest_tap => 'both'

Show events as they happen, then also display them after.

'utf8'

Set the TAP encoding to utf8

encoding => '...'

Set the TAP encoding.

EXPORTS

DEFAULT EXPORTS

tap_encoding( $ENCODING )

Set the tap encoding from this point on.

cull

Bring in results from child processes/threads. This is automatically done whenever a context is obtained, but you may wish to do it on demand.

CONSTANTS

none of these are exported by default you must request them

OUT_STD
OUT_ERR
OUT_TODO

These are indexes of specific IO handles inside an IO set (each encoding has an IO set).

STATE_COUNT
STATE_FAILED
STATE_PLAN
STATE_PASSING
STATE_LEGACY
STATE_ENDED

These are indexes into the STATE array present in the stream.

THE STREAM STACK AND METHODS

At any point there can be any number of streams. Most streams will be present in the stream stack. The stack is managed via a collection of class methods. You can always access the "current" or "central" stream using Test::Stream->shared. If you want your events to go where they are supposed to then you should always send them to the shared stream.

It is important to note that any toogle, control, listener, munger, etc. applied to a stream will effect only that stream. Independant streams, streams down the stack, and streams added later will not get any settings from other stacks. Keep this in mind if you take it upon yourself to modify the stream stack.

TOGGLES AND CONTROLS

$stream->use_fork

Turn on forking support (it cannot be turned off).

$stream->set_subtest_tap_instant($bool)
$bool = $stream->subtest_tap_instant

Render subtest events as they happen.

$stream->set_subtest_tap_delayed($bool)
$bool = $stream->subtest_tap_delayed

Render subtest events when printing the result of the subtest

$stream->set_exit_on_disruption($bool)
$bool = $stream->exit_on_disruption

When true, skip_all and bailout will call exit. When false the bailout and skip_all events will be thrown as exceptions.

$stream->set_use_tap($bool)
$bool = $stream->use_tap

Turn TAP rendering on or off.

$stream->set_use_legacy($bool)
$bool = $stream->use_legacy

Turn legacy result storing on and off.

$stream->set_use_numbers($bool)
$bool = $stream->use_numbers

Turn test numbers on and off.

SENDING EVENTS

    Test::Stream->shared->send($event)

The send() method is used to issue an event to the stream. This method will handle thread/fork sych, mungers, listeners, TAP output, etc.

ALTERING EVENTS

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

        ... Modify the event object ...

        # return is ignored.
    });

Mungers can never be removed once added. The return from a munger is ignored. Any changes you wish to make to the object must be done directly by altering it in place. The munger is called before the event is rendered as TAP, and AFTER the event has made any necessary state changes.

LISTENING FOR EVENTS

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

        ... do whatever you want with the event ...

        # return is ignored
    });

Listeners can never be removed once added. The return from a listener is ignored. Changing an event in a listener is not something you should ever do, though no protections are in place to prevent it (this may change!). The listeners are called AFTER the event has been rendered as TAP.

POST-TEST BEHAVIORS

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

        ... do whatever you need to ...

        # Return is ignored
    });

follow_up subs are called only once, when the stream recieves a finish event. There are 2 ways a finish event can occur:

done_testing

A finish event is generated when you call done_testing. The finish event occurs before the plan is output.

EXIT MAGIC

A finish event is generated when the Test::Stream END block is called, just before cleanup. This event will not happen if it was already geenerated by a call to done_testing.

OTHER METHODS

$stream->state

Get the current state of the stream. The state is an array where specific indexes have specific meanings. These indexes are managed via constants.

$stream->plan

Get the plan event, if a plan has been issued.

$stream->count

Get the test count so far.

$stream->failed

Get the number of failed tests so far.

$stream->ended

Get the context in which the tests ended, if they have ended.

$stream->legacy

Used internally to store events for legacy support.

$stream->is_passing

Check if the test is passing its plan.

$stream->done_testing($context, $max)

Tell the stream we are done testing.

$stream->fork_cull

Gather events from other threads/processes.

STACK METHODS AND INTERCEPTING EVENTS

$stream = Test::Stream->shared

Get the current shared stream. The shared stream is the stream at the top of the stack.

Test::Stream->clear

Completely remove the stream stack. It is very unlikely you will ever want to do this.

($new, $old) = Test::Stream->intercept_start($new)
($new, $old) = Test::Stream->intercept_start

Push a new stream to the top of the stack. If you do not provide a stack a new one will be created for you. If you have one created for you it will have the following differences from a default stack:

    $new->set_exit_on_disruption(0);
    $new->set_use_tap(0);
    $new->set_use_legacy(0);
Test::Stream->intercept_stop($top)

Pop the stack, you must pass in the instance you expect to be popped, there will be an exception if they do not match.

Test::Stream->intercept(sub { ... })
    Test::Stream->intercept(sub {
        my ($new, $old) = @_;

        ...
    });

Temporarily push a new stream to the top of the stack. The codeblock you pass in will be run. Once your codelbock returns the stack will be popped and restored to the previous state.

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.