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 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
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 will
62 automatically clean up after itself and restore the parent hub.
63 {
65 my $grab = grab();
66 # Things are grabbed
67 }
68 # Things are back to normal
69 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 $grab->hub->set_no_ending(0);
75 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
81 $grab = $class->new()
82 Create a new grab object, immediately starts intercepting events.
83 $ar = $grab->flush()
85 Get an arrayref of all the events so far, clearing the grab objects
86 internal list.
87 $ar = $grab->events()
89 Get an arrayref of all events so far, does not clear the internal
90 list.
91 $ar = $grab->finish()
93 Get an arrayref of all the events, then destroy the grab object.
94 $hub = $grab->hub()
96 Get the hub that is used by the grab event.
97
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 $grab->hub->set_no_ending(0);
104 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
110 Test::Stream::Plugin::Intercept - Accomplish the same thing, but using
111 blocks instead.
112
114 The source code repository for Test::Stream can be found at
115 http://github.com/Test-More/Test-Stream/.
116
118 Chad Granum <exodist@cpan.org>
119
121 Chad Granum <exodist@cpan.org>
122
124 Copyright 2015 Chad Granum <exodist7@gmail.com>.
125 This program is free software; you can redistribute it and/or modify it
127 under the same terms as Perl itself.
128 See http://dev.perl.org/licenses/
130
132 Hey! The above document had some coding errors, which are explained
133 below:
134 Around line 140:
136 '=item' outside of any '=over'
137 Around line 178:
139 You forgot a '=back' before '=head1'
140perl v5.36.0 2023-01-20 Test::Stream::Plugin::Grab(3)