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

METHODS

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

ENDING BEHAVIOR

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

SEE ALSO

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

SOURCE

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

MAINTAINERS

119       Chad Granum <exodist@cpan.org>
120

AUTHORS

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

POD ERRORS

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