Test2::Hub(3perl) | Perl Programmers Reference Guide | Test2::Hub(3perl) |
Test2::Hub - The conduit through which all events flow.
use Test2::Hub; my $hub = Test2::Hub->new(); $hub->send(...);
The hub is the place where all events get processed and handed off to the formatter. The hub also tracks test state, and provides several hooks into the event pipeline.
$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.
You can use either "filter()" or "pre_filter()", depending on your needs. Both have identical syntax, so only "filter()" is shown here.
$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);
$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);
$hub->follow_up(sub { my ($trace, $hub) = @_; ... do whatever you need to ... # Return is ignored });
follow_up subs are called only once, either when done_testing is called, or in an END block.
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 one formatter is allowed at a time.
$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->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->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.
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.
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.
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.
This object consumes Test2::Util::ExternalMeta which provides a consistent way for you to attach meta-data to instances of this class. This is useful for tools, plugins, and other extensions.
The source code repository for Test2 can be found at http://github.com/Test-More/test-more/.
Copyright 2020 Chad Granum <exodist@cpan.org>.
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/
2023-11-25 | perl v5.36.0 |