1Test2::Util::Grabber(3)User Contributed Perl DocumentatioTnest2::Util::Grabber(3)
2
3
4

NAME

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

DESCRIPTION

9       Once created this object will intercept and stash all events sent to
10       the shared Test2::Hub object. Once the object is destroyed, events will
11       once again be sent to the shared hub.
12

SYNOPSIS

14           use Test2 qw/Core Grab/;
15
16           my $grab = grab();
17
18           # Generate some events, they are intercepted.
19           ok(1, "pass");
20           ok(0, "fail");
21
22           my $events_a = $grab->flush;
23
24           # Generate some more events, they are intercepted.
25           ok(1, "pass");
26           ok(0, "fail");
27
28           # Same as flush, except it destroys the grab object.
29           my $events_b = $grab->finish;
30
31       After calling "finish()" the grab object is destroyed and $grab is set
32       to undef. $events_a is an arrayref with the first two events. $events_b
33       is an arrayref with the second two events.
34

EXPORTS

36       $grab = grab()
37           This lets you intercept all events for a section of code without
38           adding anything to your call stack. This is useful for things that
39           are sensitive to changes in the stack depth.
40
41               my $grab = grab();
42                   ok(1, 'foo');
43                   ok(0, 'bar');
44
45               # $grab is magically undef after this.
46               my $events = $grab->finish;
47
48               is(@$events, 2, "grabbed two events.");
49
50           When you call "finish()" the $grab object will automagically undef
51           itself, but only for the reference used in the method call. If you
52           have other references to the $grab object they will not be set to
53           undef.
54
55           If the $grab object is destroyed without calling "finish()", it
56           will automatically clean up after itself and restore the parent
57           hub.
58
59               {
60                   my $grab = grab();
61                   # Things are grabbed
62               }
63               # Things are back to normal
64
65           By default the hub used has "no_ending" set to true. This will
66           prevent the hub from enforcing that you issued a plan and ran at
67           least one test. You can turn enforcement back one like this:
68
69               $grab->hub->set_no_ending(0);
70
71           With "no_ending" turned off, "finish" will run the post-test checks
72           to enforce the plan and that tests were run. In many cases this
73           will result in additional events in your events array.
74

METHODS

76       $grab = $class->new()
77           Create a new grab object, immediately starts intercepting events.
78
79       $ar = $grab->flush()
80           Get an arrayref of all the events so far, clearing the grab objects
81           internal list.
82
83       $ar = $grab->events()
84           Get an arrayref of all events so far. Does not clear the internal
85           list.
86
87       $ar = $grab->finish()
88           Get an arrayref of all the events, then destroy the grab object.
89
90       $hub = $grab->hub()
91           Get the hub that is used by the grab event.
92

ENDING BEHAVIOR

94       By default the hub used has "no_ending" set to true. This will prevent
95       the hub from enforcing that you issued a plan and ran at least one
96       test. You can turn enforcement back one like this:
97
98           $grab->hub->set_no_ending(0);
99
100       With "no_ending" turned off, "finish" will run the post-test checks to
101       enforce the plan and that tests were run. In many cases this will
102       result in additional events in your events array.
103

SEE ALSO

105       Test2::Tools::Intercept - Accomplish the same thing, but using blocks
106       instead.
107

SOURCE

109       The source code repository for Test2 can be found at
110       https://github.com/Test-More/Test2-Suite/.
111

MAINTAINERS

113       Chad Granum <exodist@cpan.org>
114

AUTHORS

116       Chad Granum <exodist@cpan.org>
117

119       Copyright 2018 Chad Granum <exodist@cpan.org>.
120
121       This program is free software; you can redistribute it and/or modify it
122       under the same terms as Perl itself.
123
124       See http://dev.perl.org/licenses/
125
126
127
128perl v5.36.0                      2022-07-22           Test2::Util::Grabber(3)
Impressum