1Test::Stream::Plugin::GUrsaebr(3C)ontributed Perl DocumeTnetsatt:i:oSntream::Plugin::Grab(3)
2
6 Test::Stream::Plugin::Grab - Object used to temporarily intercept all
7 events.
8
10 This distribution is deprecated in favor of Test2, Test2::Suite, and
11 Test2::Workflow.
12 See Test::Stream::Manual::ToTest2 for a conversion guide.
14
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
21 use Test::Stream qw/Core Grab/;
22 my $grab = grab();
24 # Generate some events, they are intercepted.
26 ok(1, "pass");
27 ok(0, "fail");
28 my $events_a = $grab->flush;
30 # Generate some more events, they are intercepted.
32 ok(1, "pass");
33 ok(0, "fail");
34 # Same as flush, except it destroys the grab object.
36 my $events_b = $grab->finish;
37 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
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 my $grab = grab();
49 ok(1, 'foo');
50 ok(0, 'bar');
51 # $grab is magically undef after this.
53 my $events = $grab->finish;
54 is(@$events, 2, "grabbed 2 events.");
56 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 If the $grab object is destroyed without calling "finish()", it
62 will automatically clean up after itself and restore the parent
63 hub.
64 {
66 my $grab = grab();
67 # Things are grabbed
68 }
69 # Things are back to normal
70 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 $grab->hub->set_no_ending(0);
76 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
82 $grab = $class->new()
83 Create a new grab object, immediately starts intercepting events.
84 $ar = $grab->flush()
86 Get an arrayref of all the events so far, clearing the grab objects
87 internal list.
88 $ar = $grab->events()
90 Get an arrayref of all events so far, does not clear the internal
91 list.
92 $ar = $grab->finish()
94 Get an arrayref of all the events, then destroy the grab object.
95 $hub = $grab->hub()
97 Get the hub that is used by the grab event.
98
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 $grab->hub->set_no_ending(0);
105 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
111 Test::Stream::Plugin::Intercept - Accomplish the same thing, but using
112 blocks instead.
113
115 The source code repository for Test::Stream can be found at
116 http://github.com/Test-More/Test-Stream/.
117
119 Chad Granum <exodist@cpan.org>
120
122 Chad Granum <exodist@cpan.org>
123
125 Copyright 2015 Chad Granum <exodist7@gmail.com>.
126 This program is free software; you can redistribute it and/or modify it
128 under the same terms as Perl itself.
129 See http://dev.perl.org/licenses/
131
133 Hey! The above document had some coding errors, which are explained
134 below:
135 Around line 140:
137 '=item' outside of any '=over'
138 Around line 178:
140 You forgot a '=back' before '=head1'
141perl v5.34.0 2021-07-27 Test::Stream::Plugin::Grab(3)