The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test2-0.000015
++
/ Test2::Hub

NAME

Test2::Hub - The conduit through which all events flow.

EXPERIMENTAL RELEASE

This is an experimental release. Using this right now is not recommended.

SYNOPSIS

    use Test2::Hub;

    my $hub = Test2::Hub->new();
    $hub->send(...);

DESCRIPTION

The hub is the place where all events get processed and handed off to the formatter. The hub also tracks test state, and provides everal hooks into the event pipeline.

COMMON TASKS

SENDING EVENTS

    $hub->send($event)

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

ALTERING OR REMOVING EVENTS

    $hub->filter(sub {
        my ($hub, $event) = @_;

        my $action = get_action($event);

        # No action should be taken
        return $event if $action eq 'none';

        # You want your filter to remove the event
        return undef if $action eq 'delete';

        if ($action eq 'do_it') {
            my $new_event = copy_event($event);
            ... Change your copy of the event ...
            return $new_event;
        }

        die "Should not happen";
    });

By default filters are not inherited by child hubs, that means if you start a subtest, the subtest will not inherit the filter. You can change this behavior with the inherit parameter:

    $hub->filter(sub { ... }, inherit => 1);

LISTENING FOR EVENTS

    $hub->listen(sub {
        my ($hub, $event, $number) = @_;

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

        # return is ignored
    });

By default listeners are not inherited by child hubs, that means if you start a subtest, the subtest will not inherit the listener. You can change this behavior with the inherit parameter:

    $hub->listen(sub { ... }, inherit => 1);

POST-TEST BEHAVIORS

    $hub->follow_up(sub {
        my ($trace, $hub) = @_;

        ... do whatever you need to ...

        # Return is ignored
    });

follow_up subs are called only once, ether when done_testing is called, or in an END block.

SETTING THE FORMATTER

By default an instance of Test2::Formatter::TAP is created and used.

    my $old = $hub->format(My::Formatter->new);

Setting the formatter will REPLACE any existing formatter. You may set the formatter to undef to prevent output. The old formatter will be returned if one was already set. Only 1 formatter is allowed at a time.

METHODS

$hub->send($event)

This is where all events enter the hub for processing.

$hub->process($event)

This is called by send after it does any IPC handling. You can use this to bypass the IPC process, but in general you should avoid using this.

$val = $hub->meta($key)
$val = $hub->meta($key, $default)

This method is made available to allow third party plugins to associate meta-data with a hub. It is recommended that all third party plugins use their module namespace as their meta-data key.

This method always returns the value for the key. If there is no value it will be initialized to $default, in which case $default is also returned.

Recommended usage:

    my $meta = $hub->meta(__PACKAGE__, {});
    unless ($meta->{foo}) {
        $meta->{foo} = 1;
        $meta->{bar} = 2;
    }
$val = $hub->delete_meta($key)

This will delete all data in the specified metadata key.

$val = $hub->get_meta($key)

This method will retrieve the value of any meta-data key specified.

$old = $hub->format($formatter)

Replace the existing formatter instance with a new one. Formatters must be objects that implement a $formatter->write($event) method.

$sub = $hub->listen(sub { ... })

You can use this to record all events AFTER they have been sent to the formatter. No changes made here will be meaningful, except possibly to other listeners.

    $hub->listen(sub {
        my ($hub, $event, $number) = @_;

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

        # return is ignored
    });

Normally listeners are not inherited by child hubs such as subtests. You can add the inherit => 1 parameter to allow a listener to be inherited.

$hub->unlisten($sub)

You can use this to remove a listen callback. You must pass in the coderef returned by the listen() method.

$hub->follow_op(sub { ... })

Use this to add behaviors that are called just before the hub is finalized. The only argument to your codeblock will be a Test2::Util::Trace instance.

    $hub->follow_up(sub {
        my ($trace, $hub) = @_;

        ... do whatever you need to ...

        # Return is ignored
    });

follow_up subs are called only once, ether when done_testing is called, or in an END block.

$sub = $hub->add_context_init(sub { ... });

This allows you to add callbacks that will trigger every time a new context is created for the hub. The only argument to the sub will be the Test2::API::Context instance that was created.

Note Using this hook could have a huge performance impact.

The coderef you provide is returned and can be used to remove the hook later.

$hub->remove_context_init($sub);

This can be used to remove a context init hook.

$sub = $hub->add_context_release(sub { ... });

This allows you to add callbacks that will trigger every time a context for this hub is released. The only argument to the sub will be the Test2::API::Context instance that was released. These will run in reverse order.

Note Using this hook could have a huge performance impact.

The coderef you provide is returned and can be used to remove the hook later.

$hub->remove_context_release($sub);

This can be used to remove a context release hook.

$hub->cull()

Cull any IPC events (and process them).

$pid = $hub->pid()

Get the process id under which the hub was created.

$tid = $hub->tid()

Get the thread id under which the hub was created.

$hud = $hub->hid()

Get the identifier string of the hub.

$ipc = $hub->ipc()

Get the IPC object used by the hub.

$hub->set_no_ending($bool)
$bool = $hub->no_ending

This can be used to disable auto-ending behavior for a hub. The auto-ending behavior is triggered by an end block and is used to cull IPC events, and output the final plan if the plan was 'no_plan'.

STATE METHODS

$hub->reset_state()

Reset all state to the start. This sets the test count to 0, clears the plan, removes the failures, etc.

$num = $hub->count

Get the number of tests that have been run.

$num = $hub->failed

Get the number of failures (Not all failures come from a test fail, so this number can be larger than the count).

$bool = $hub->ended

True if the testing has ended. This MAY return the stack frame of the tool that ended the test, but that is not guarenteed.

$bool = $hub->is_passing
$hub->is_passing($bool)

Check if the overall test run is a failure. Can also be used to set the pass/fail status.

$hub->plan($plan)
$plan = $hub->plan

Get or set the plan. The plan must be an integer larger than 0, the string 'no_plan', or the string 'skip_all'.

$bool = $hub->check_plan

Check if the plan and counts match, but only if the tests have ended. If tests have not unded this will return undef, otherwise it will be a true/false.

SOURCE

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

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2015 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://dev.perl.org/licenses/