1Test::Stream::Plugin::GUrsaebr(3C)ontributed Perl DocumeTnetsatt:i:oSntream::Plugin::Grab(3)
2
3
4

NAME

6       Test::Stream::Plugin::Grab - Object used to temporarily intercept all
7       events.
8

DEPRECATED

10       This distribution is deprecated in favor of Test2, Test2::Suite, and
11       Test2::Workflow.
12
13       See Test::Stream::Manual::ToTest2 for a conversion guide.
14

DESCRIPTION

16       Once created this object will intercept and stash all events sent to
17       the shared Test::Stream::Hub object. Once the object is destroyed
18       events will once again be sent to the shared hub.
19

SYNOPSIS

21           use Test::Stream qw/Core Grab/;
22
23           my $grab = grab();
24
25           # Generate some events, they are intercepted.
26           ok(1, "pass");
27           ok(0, "fail");
28
29           my $events_a = $grab->flush;
30
31           # Generate some more events, they are intercepted.
32           ok(1, "pass");
33           ok(0, "fail");
34
35           # Same as flush, except it destroys the grab object.
36           my $events_b = $grab->finish;
37
38       After calling finish() the grab object is destroyed and $grab is set to
39       undef. $events_a is an arrayref with the first 2 events. $events_b is
40       an arrayref with the second 2 events.
41

EXPORTS

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

METHODS

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

ENDING BEHAVIOR

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

SEE ALSO

110       Test::Stream::Plugin::Intercept - Accomplish the same thing, but using
111       blocks instead.
112

SOURCE

114       The source code repository for Test::Stream can be found at
115       http://github.com/Test-More/Test-Stream/.
116

MAINTAINERS

118       Chad Granum <exodist@cpan.org>
119

AUTHORS

121       Chad Granum <exodist@cpan.org>
122
124       Copyright 2015 Chad Granum <exodist7@gmail.com>.
125
126       This program is free software; you can redistribute it and/or modify it
127       under the same terms as Perl itself.
128
129       See http://dev.perl.org/licenses/
130

POD ERRORS

132       Hey! The above document had some coding errors, which are explained
133       below:
134
135       Around line 140:
136           '=item' outside of any '=over'
137
138       Around line 178:
139           You forgot a '=back' before '=head1'
140
141
142
143perl v5.36.0                      2023-01-20     Test::Stream::Plugin::Grab(3)
Impressum