NAME

Test::Stream::API - Single point of access to Test::Stream extendability features.

DESCRIPTION

There are times where you want to extend or alter the bahvior of a test file or test suite. This module collects all the features and tools that Test::Stream offers for such actions. Everything in this file is accessible in other places, but with less sugar coating.

SYNOPSYS

Nothing is exported by default, you must request it.

use Test::Stream::API qw/ ... /;

MODIFYING EVENTS

use Test::Stream::API qw/ munge /;

munge {
    my ($stream, $event, @subevents) = @_;

    if($event->isa('Test::Stream::Diag')) {
        $event->set_message( "KILROY WAS HERE: " . $event->message );
    }
};

REPLACING TAP WITH ALTERNATIVE OUTPUT

use Test::Stream::API qw/ disable_tap listen /;

disable_tap();

listen {
    my $stream = shift;
    my ($event, @subevents) = @_;

    # Tracking results in a db?
    my $id = log_event_to_db($e);
    log_subevent_to_db($id, $_) for @subevents;
}

END OF TEST BEHAVIORS

use Test::Stream::API qw/ follow_up is_passing /;

follow_up {
    my ($context) = @_;

    if (is_passing()) {
        print "KILROY Says the test file passed!\n";
    }
    else {
        print "KILROY is not happy with you!\n";
    }
};

ENABLING FORKING SUPPORT

use Test::More;
use Test::Stream::API qw/ enable_forking /;

enable_forking();

# This all just works now!
my $pid = fork();
if ($pid) { # Parent
    ok(1, "From Parent");
}
else { # child
    ok(1, "From Child");
    exit 0;
}

done_testing;

Note: Result order between processes is not guarenteed, but the test number is handled for you meaning you don't need to care.

Results:

ok 1 - From Child
ok 2 - From Parent

Or:

ok 1 - From Parent
ok 2 - From Child

REDIRECTING TAP OUTPUT

You may omit any arguments to leave a specific handle unchanged. It is not possible to set a handle to undef or 0 or any other false value.

use Test::Stream::API qw/ set_tap_outputs /;

set_tap_outputs(
    encoding => 'legacy',           # Default,
    std      => $STD_IO_HANDLE,     # equivilent to $TB->output()
    err      => $ERR_IO_HANDLE,     # equivilent to $TB->failure_output()
    todo     => $TODO_IO_HANDLE,    # equivilent to $TB->todo_output()
);

Note: Each encoding has independant filehandles.

GENERATING EVENTS

EASY WAY

The best way to generate an event is through a Test::Stream::Context object. All events have a method associated with them on the context object. The method will be the last part of the evene package name lowercased, for example Test::Stream::Event::Ok can be issued via $context->ok(...).

use Test::Stream::API qw/ context /;
my $context = context();
$context->EVENT_TYPE(...);

The arguments to the event method are the values for event accessors in order, excluding the context, created, and in_subtest arguments. For instance here is how the Ok event is defined:

package Test::Stream::Event::Ok;
use Test::Stream::Event(
    accessors  => [qw/real_bool name diag .../],
    ...
);

This means that the $context->ok method takes up to 5 arguments. The first argument is a boolean true/false, the second is the name of the test, and the third is an arrayref of diagnostics messages or Test::Stream::Event::Diag objects.

$context->ok($bool, $name, [$diag]);

Here are the main event methods, as well as their standard arguments:

$context->ok($bool, $name, \@diag): Issue an Test::Stream::Event::Ok event.
$context->diag($msg): Issue an Test::Stream::Event::Diag event.
$context->note($msg): Issue an Test::Stream::Event::Note event.
$context->plan($max, $directive, $reason): Issue an Test::Stream::Event::Plan event. $max is the number of expected tests. $directive is a plan directive such as 'no_plan' or 'skip_all'. $reason is the reason for the directive (only applicable to skip_all).
$context->bail($reason): Issue an Test::Stream::Event::Bail event.

HARD WAY

This is not recommended, but it demonstrates just how much the context shortcut methods do for you.

# First make a context
my $context = Test::Stream::Context->new_from_pairs(
    frame     => ..., # Where to report errors
    stream    => ..., # Test::Stream object to use
    encoding  => ..., # encoding from test package meta-data
    in_todo   => ..., # Are we in a todo?
    todo      => ..., # Which todo message should be used?
    modern    => ..., # Is the test package modern?
    pid       => ..., # Current PID
    skip      => ..., # Are we inside a 'skip' state?
    provider  => ..., # What tool created the context?
);

# Make the event
my $ok = Test::Stream::Event::Ok->new_from_pairs(
    # Should reflect where the event was produced, NOT WHERE ERRORS ARE REPORTED
    created => [__PACKAGE__, __FILE__,              __LINE__],
    context => $context,     # A context is required
    in_subtest => 0,

    bool => $bool,
    name => $name,
    diag => \@diag,
);

# Send the event to the stream.
Test::Stream->shared->send($ok);

EXPORTED FUNCTIONS

All of these are functions. These functions all effect the current-shared Test::Stream object only.

EVENT MANAGEMENT

These let you install a callback that is triggered for all primary events. The first argument is the Test::Stream object, the second is the primary Test::Stream::Event, any additional arguments are subevents. All subevents are Test::Stream::Event objects which are directly tied to the primary one. The main example of a subevent is the failure Test::Stream::Event::Diag object associated with a failed Test::Stream::Event::Ok, events within a subtest are another example.

listen { my ($stream, $event, @subevents) = @_; ... }: Listen callbacks happen just after TAP is rendered (or just after it would be rendered if TAP is disabled).
munge { my ($stream, $event, @subevents) = @_; ... }: Muinspect_todonge callbacks happen just before TAP is rendered (or just before it would be rendered if TAP is disabled).

POST-TEST BEHAVIOR

follow_up { my ($context) = @_; ... }

A followup callback allows you to install behavior that happens either when done_testing() is called, or when the test file completes.

CAVEAT: If done_testing is not used, the callback will happen in the END {...} block used by Test::Stream to enact magic at the end of the test.

CONCURRENCY

enable_forking(): Turns forking support on. This turns on a synchronization method that *just works* when you fork inside a test. This must be turned on prior to any forking.
cull(): This can only be called in the main process or thread. This is a way to manually pull in results from other processes or threads. Typically this happens automatically, but this allows you to ensure results have been gathered by a specific point.

CONTROL OVER TAP

enable_tap()

Turn TAP on (on by default).

disable_tap()

Turn TAP off.

enable_numbers()

Show test numbers when rendering TAP.

disable_numbers()

Do not show test numbers when rendering TAP.

subtest_tap_instant()

This is the default way to render subtests:

# Subtest: a_subtest
    ok 1 - pass
    1..1
ok 1 - a_subtest

Using this will automatically turn off subtest_tap_delayed

subtest_tap_delayed()

This is an alternative way to render subtests, this method waits until the subtest is complete then renders it in a structured way:

ok 1 - a_subtest {
    ok 1 - pass
    1..1
}

Using this will automatically turn off subtest_tap_instant

tap_encoding($ENCODING)

This lets you change the encoding for TAP output. This only effects the current test package.

set_tap_outputs(encoding => 'legacy', std => $IO, err => $IO, todo => $IO)

This lets you replace the filehandles used to output TAP for any specific encoding. All fields are optional, any handles not specified will not be changed. The encoding parameter defaults to 'legacy'.

Note: The todo handle is used for failure output inside subtests where the subtest was started already in todo.

$hashref = get_tap_outputs($encoding)

'legacy' is used when encoding is not specified.

Returns a hashref with the output handles:

{
    encoding => $encoding,
    std      => $STD_HANDLE,
    err      => $ERR_HANDLE,
    todo     => $TODO_HANDLE,
}

Note: The todo handle is used for failure output inside subtests where the subtest was started already in todo.

TEST PACKAGE METADATA

$bool = is_modern($package)

Check if a test package has the 'modern' flag.

Note: Throws an exception if $package is not already a test package.

set_modern($package, $value)

Turn on the modern flag for the specified test package.

Note: Throws an exception if $package is not already a test package.

TODO MANAGEMENT

push_todo($todo)

$todo = pop_todo()

$todo = peek_todo()

These can be used to manipulate a global todo state. When a true value is at the top of the todo stack it will effect any events generated via an Test::Stream::Context object. Typically all events are generated this way.

set_todo($package, $todo)

This lets you set the todo state for the specified test package. This will throw an exception if the package is not a test package.

$todo_hashref = inspect_todo($package)

$todo_hashref = inspect_todo()

This lets you inspect the TODO state. Optionally you can specify a package to inspect. The return is a hashref with several keys:

{
    TODO => $TODO_STACK_ARRAYREF,
    TB   => $TEST_BUILDER_TODO_STATE,
    META => $PACKAGE_METADATA_TODO_STATE,
    PKG  => $package::TODO,
}

This lets you see what todo states are set where. This is primarily useful when debugging to see why something is unexpectedly TODO, or when something is not TODO despite expectations.

TEST PACKAGE MANAGEMENT

$meta = is_tester($package): Check if a package is a tester, if it is the meta-object for the tester is returned.
$meta = init_tester($package): Set the package as a tester and return the meta-object. If the package is already a tester it will return the existing meta-object.

CONTEXTUAL INFORMATION

$context = context()

$context = context($add_level)

This will get the correct Test::Stream::Context object. This may be one that was previously initialized, or it may generate a new one. Read the Test::Stream::Context documentation for more info.

Note, context() assumes you are at the lowest level of your tool, and looks at the current caller. If you need it to look further you can call it with a numeric argument which is added to the level. To clarify, calling context() is the same as calling context(0).

$stream = current_stream()

This will return the current Test::Stream Object. Test::Stream objects typically live on a global stack, the topmost item on the stack is the one that is normally used.

CAPTURING EVENTS

$events_arrayref = intercept { ... };

Any events generated inside the codeblock will be intercepted and returned. No events within the block will go to the real Test::Stream instance.

Note: This comes from the Test::Stream::Tester package which provides addiitonal tools that are useful for testing/validating events.

TEST STATE

$num = state_count(): Check how many tests have been run.
$num = state_failed(): Check how many tests have failed.
$plan_event = state_plan(): Check if a plan has been issued, if so the Test::Stream::Event::Plan instance will be returned.
$bool = state_ended(): True if the test is complete (after done_testing).
$bool = is_passing(): Check if the test state is passing.

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

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.

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

Under the same license as Perl itself

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

Test::Builder::Tester

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

To install Test::Simple, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Test::Simple

CPAN shell

perl -MCPAN -e shell
install Test::Simple

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

SYNOPSYS

MODIFYING EVENTS

REPLACING TAP WITH ALTERNATIVE OUTPUT

END OF TEST BEHAVIORS

ENABLING FORKING SUPPORT

REDIRECTING TAP OUTPUT

GENERATING EVENTS

EASY WAY

HARD WAY

EXPORTED FUNCTIONS

EVENT MANAGEMENT

POST-TEST BEHAVIOR

CONCURRENCY

CONTROL OVER TAP

TEST PACKAGE METADATA

TODO MANAGEMENT

TEST PACKAGE MANAGEMENT

CONTEXTUAL INFORMATION

CAPTURING EVENTS

TEST STATE

SOURCE

MAINTAINER

AUTHORS

COPYRIGHT

Module Install Instructions