<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">package Test2::Util::Grabber;
use strict;
use warnings;

our $VERSION = '0.000162';

use Test2::Hub::Interceptor();
use Test2::EventFacet::Trace();

use Test2::API qw/test2_stack test2_ipc/;

use Test2::Util::HashBase qw/hub finished _events term_size &lt;state &lt;trace/;

sub init {
    my $self = shift;

    # Make sure we have a hub on the stack
    test2_stack-&gt;top();

    my $hub = test2_stack-&gt;new_hub(
        class =&gt; 'Test2::Hub::Interceptor',
        formatter =&gt; undef,
        no_ending =&gt; 1,
    );

    $self-&gt;{+HUB} = $hub;

    my @events;
    $hub-&gt;listen(sub { push @events =&gt; $_[1] });

    $self-&gt;{+_EVENTS} = \@events;

    $self-&gt;{+TERM_SIZE} = $ENV{TS_TERM_SIZE};
    $ENV{TS_TERM_SIZE} = 80;

    my $trace = $self-&gt;{+TRACE} ||= Test2::EventFacet::Trace-&gt;new(frame =&gt; [caller(1)]);
    my $state = $self-&gt;{+STATE} ||= {};
    $hub-&gt;clean_inherited(trace =&gt; $trace, state =&gt; $state);

    return;
}

sub flush {
    my $self = shift;
    my $out = [@{$self-&gt;{+_EVENTS}}];
    @{$self-&gt;{+_EVENTS}} = ();
    return $out;
}

sub events {
    my $self = shift;
    # Copy
    return [@{$self-&gt;{+_EVENTS}}];
}

sub finish {
    my ($self) = @_; # Do not shift;
    $_[0] = undef;

    if (defined $self-&gt;{+TERM_SIZE}) {
        $ENV{TS_TERM_SIZE} = $self-&gt;{+TERM_SIZE};
    }
    else {
        delete $ENV{TS_TERM_SIZE};
    }

    my $hub = $self-&gt;{+HUB};

    $self-&gt;{+FINISHED} = 1;
    test2_stack()-&gt;pop($hub);

    my $trace = $self-&gt;{+TRACE} ||= Test2::EventFacet::Trace-&gt;new(frame =&gt; [caller(1)]);
    my $state = $self-&gt;{+STATE} ||= {};
    $hub-&gt;clean_inherited(trace =&gt; $trace, state =&gt; $state);

    my $dbg = Test2::EventFacet::Trace-&gt;new(
        frame =&gt; [caller(0)],
    );
    $hub-&gt;finalize($dbg, 1)
        if !$hub-&gt;no_ending
        &amp;&amp; !$hub-&gt;state-&gt;ended;

    return $self-&gt;flush;
}

sub DESTROY {
    my $self = shift;
    return if $self-&gt;{+FINISHED};
    test2_stack-&gt;pop($self-&gt;{+HUB});
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Test2::Util::Grabber - Object used to temporarily intercept all events.

=head1 DESCRIPTION

Once created this object will intercept and stash all events sent to the shared
L&lt;Test2::Hub&gt; object. Once the object is destroyed, events will once
again be sent to the shared hub.

=head1 SYNOPSIS

    use Test2 qw/Core Grab/;

    my $grab = grab();

    # Generate some events, they are intercepted.
    ok(1, "pass");
    ok(0, "fail");

    my $events_a = $grab-&gt;flush;

    # Generate some more events, they are intercepted.
    ok(1, "pass");
    ok(0, "fail");

    # Same as flush, except it destroys the grab object.
    my $events_b = $grab-&gt;finish;

After calling C&lt;finish()&gt; the grab object is destroyed and C&lt;$grab&gt; is set to
undef. C&lt;$events_a&gt; is an arrayref with the first two events. C&lt;$events_b&gt; is an
arrayref with the second two events.

=head1 EXPORTS

=over 4

=item $grab = grab()

This lets you intercept all events for a section of code without adding
anything to your call stack. This is useful for things that are sensitive to
changes in the stack depth.

    my $grab = grab();
        ok(1, 'foo');
        ok(0, 'bar');

    # $grab is magically undef after this.
    my $events = $grab-&gt;finish;

    is(@$events, 2, "grabbed two events.");

When you call C&lt;finish()&gt; the C&lt;$grab&gt; object will automagically undef itself,
but only for the reference used in the method call. If you have other
references to the C&lt;$grab&gt; object they will not be set to undef.

If the C&lt;$grab&gt; object is destroyed without calling C&lt;finish()&gt;, it will
automatically clean up after itself and restore the parent hub.

    {
        my $grab = grab();
        # Things are grabbed
    }
    # Things are back to normal

By default the hub used has C&lt;no_ending&gt; set to true. This will prevent the hub
from enforcing that you issued a plan and ran at least one test. You can turn
enforcement back one like this:

    $grab-&gt;hub-&gt;set_no_ending(0);

With C&lt;no_ending&gt; turned off, C&lt;finish&gt; will run the post-test checks to
enforce the plan and that tests were run. In many cases this will result in
additional events in your events array.

=back

=head1 METHODS

=over 4

=item $grab = $class-&gt;new()

Create a new grab object, immediately starts intercepting events.

=item $ar = $grab-&gt;flush()

Get an arrayref of all the events so far, clearing the grab objects internal
list.

=item $ar = $grab-&gt;events()

Get an arrayref of all events so far. Does not clear the internal list.

=item $ar = $grab-&gt;finish()

Get an arrayref of all the events, then destroy the grab object.

=item $hub = $grab-&gt;hub()

Get the hub that is used by the grab event.

=back

=head1 ENDING BEHAVIOR

By default the hub used has C&lt;no_ending&gt; set to true. This will prevent the hub
from enforcing that you issued a plan and ran at least one test. You can turn
enforcement back one like this:

    $grab-&gt;hub-&gt;set_no_ending(0);

With C&lt;no_ending&gt; turned off, C&lt;finish&gt; will run the post-test checks to
enforce the plan and that tests were run. In many cases this will result in
additional events in your events array.

=head1 SEE ALSO

L&lt;Test2::Tools::Intercept&gt; - Accomplish the same thing, but using
blocks instead.

=head1 SOURCE

The source code repository for Test2 can be found at
F&lt;https://github.com/Test-More/Test2-Suite/&gt;.

=head1 MAINTAINERS

=over 4

=item Chad Granum E&lt;lt&gt;exodist@cpan.orgE&lt;gt&gt;

=back

=head1 AUTHORS

=over 4

=item Chad Granum E&lt;lt&gt;exodist@cpan.orgE&lt;gt&gt;

=back

=head1 COPYRIGHT

Copyright 2018 Chad Granum E&lt;lt&gt;exodist@cpan.orgE&lt;gt&gt;.

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

See F&lt;http://dev.perl.org/licenses/&gt;

=cut
</pre></body></html>