NAME

SYNOPSIS

    use Test2::Hub;

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

DESCRIPTION

COMMON TASKS

    $hub->send($event)

    $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";
    });

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

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

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

        # return is ignored
    });

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

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

        ... do whatever you need to ...

        # Return is ignored
    });

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

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.

$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 { ... }, %optional_params)

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.

$sub = $hub->filter(sub { ... }, %optional_params)

$sub = $hub->pre_filter(sub { ... }, %optional_params)

These can be used to add filters. Filters can modify, replace, or remove events before anything else can see them.

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

            return $event;    # No Changes
            return;           # Remove the event

            # Or you can modify an event before returning it.
            $event->modify;
            return $event;
        }
    );
    

If you are not using threads, forking, or IPC then the only difference between a "filter" and a "pre_filter" is that "pre_filter" subs run first. When you are using threads, forking, or IPC, pre_filters happen to events before they are sent to their destination proc/thread, ordinary filters happen only in the destination hub/thread.

You cannot add a regular filter to a hub if the hub was created in another process or thread. You can always add a pre_filter.

$hub->unfilter($sub)

$hub->pre_unfilter($sub)

These can be used to remove filters and pre_filters. The $sub argument is the reference returned by "filter()" or "pre_filter()".

$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::EventFacet::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_acquire(sub { ... });

Add a callback that will be called every time someone tries to acquire a context. It gets a single argument, a reference of the hash of parameters being used the construct the context. This is your chance to change the parameters by directly altering the hash.

    test2_add_callback_context_acquire(sub {
        my $params = shift;
        $params->{level}++;
    });
    

This is a very scary API function. Please do not use this unless you need to. This is here for Test::Builder and backwards compatibility. This has you directly manipulate the hash instead of returning a new one for performance reasons.

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_acquire($sub);

This can be used to remove a context acquire hook.

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

$uuid = $hub->uuid()

If UUID tagging is enabled (see Test2::API) then the hub will have a UUID.

$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'.

$bool = $hub->active

$hub->set_active($bool)

These are used to get/set the 'active' attribute. When true this attribute will force "hub->finalize()" to take action even if there is no plan, and no tests have been run. This flag is useful for plugins that add follow-up behaviors that need to run even if no events are seen.

THIRD PARTY META-DATA

SOURCE

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

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/