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 to
32       undef. $events_a is an arrayref with the first two events. $events_b is
33       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 will
56           automatically clean up after itself and restore the parent hub.
57
58               {
59                   my $grab = grab();
60                   # Things are grabbed
61               }
62               # Things are back to normal
63
64           By default the hub used has "no_ending" set to true. This will
65           prevent the hub from enforcing that you issued a plan and ran at
66           least one test. You can turn enforcement back one like this:
67
68               $grab->hub->set_no_ending(0);
69
70           With "no_ending" turned off, "finish" will run the post-test checks
71           to enforce the plan and that tests were run. In many cases this
72           will result in additional events in your events array.
73

METHODS

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

ENDING BEHAVIOR

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

SEE ALSO

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

SOURCE

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

MAINTAINERS

112       Chad Granum <exodist@cpan.org>
113

AUTHORS

115       Chad Granum <exodist@cpan.org>
116

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