1Test2::API::InterceptReUssuelrt(C3o)ntributed Perl DocumTeenstta2t:i:oAnPI::InterceptResult(3)
2
6 Test2::API::InterceptResult - Representation of a list of events.
7
9 This class represents a list of events, normally obtained using
10 intercept() from Test2::API.
11 This class is intended for people who with to verify the results of
13 test tools they write.
14 This class provides methods to normalize, summarize, or map the list of
16 events. The output of these operations makes verifying your testing
17 tools and the events they generate significantly easier. In most cases
18 this spares you from needing a deep understanding of the event/facet
19 model.
20
22 Usually you get an instance of this class when you use intercept() from
23 Test2::API.
24 use Test2::V0;
26 use Test2::API qw/intercept/;
27 my $events = intercept {
29 ok(1, "pass");
30 ok(0, "fail");
31 todo "broken" => sub { ok(0, "fixme") };
32 plan 3;
33 };
34 # This is typically the most useful construct
36 # squash_info() merges assertions and diagnostics that are associated
37 # (and returns a new instance with the modifications)
38 # flatten() condenses the facet data into the key details for each event
39 # (and returns those structures in an arrayref)
40 is(
41 $events->squash_info->flatten(),
42 [
43 {
44 causes_failure => 0,
45 name => 'pass',
47 pass => 1,
48 trace_file => 'xxx.t',
50 trace_line => 5,
51 },
52 {
53 causes_failure => 1,
54 name => 'fail',
56 pass => 0,
57 trace_file => 'xxx.t',
59 trace_line => 6,
60 # There can be more than one diagnostics message so this is
62 # always an array when present.
63 diag => ["Failed test 'fail'\nat xxx.t line 6."],
64 },
65 {
66 causes_failure => 0,
67 name => 'fixme',
69 pass => 0,
70 trace_file => 'xxx.t',
72 trace_line => 7,
73 # There can be more than one diagnostics message or todo
75 # reason, so these are always an array when present.
76 todo => ['broken'],
77 # Diag message was turned into a note since the assertion was
79 # TODO
80 note => ["Failed test 'fixme'\nat xxx.t line 7."],
81 },
82 {
83 causes_failure => 0,
84 plan => 3,
86 trace_file => 'xxx.t',
88 trace_line => 8,
89 },
90 ],
91 "Flattened events look like we expect"
92 );
93 See Test2::API::InterceptResult::Event for a full description of what
95 flatten() provides for each event.
96
98 Please note that no methods modify the original instance unless asked
99 to do so.
100 CONSTRUCTION
102 $events = Test2::API::InterceptResult->new(@EVENTS)
103 $events = Test2::API::InterceptResult->new_from_ref(\@EVENTS)
104 These create a new instance of Test2::API::InterceptResult from the
105 given events.
106 In the first form a new blessed arrayref is returned. In the
108 'new_from_ref' form the reference you pass in is directly blessed.
109 Both of these will throw an exception if called in void context.
111 This is mainly important for the 'filtering' methods listed below
112 which normally return a new instance, they throw an exception in
113 such cases as it probably means someone meant to filter the
114 original in place.
115 $clone = $events->clone()
117 Make a clone of the original events. Note that this is a deep copy,
118 the entire structure is duplicated. This uses "dclone" from
119 Storable to achieve the deep clone.
120 NORMALIZATION
122 @events = $events->event_list
123 This returns all the events in list-form.
124 $hub = $events->hub
126 This returns a new Test2::Hub instance that has processed all the
127 events contained in the instance. This gives you a simple way to
128 inspect the state changes your events cause.
129 $state = $events->state
131 This returns a summary of the state of a hub after processing all
132 the events.
133 {
135 count => 2, # Number of assertions made
136 failed => 1, # Number of test failures seen
137 is_passing => 0, # Boolean, true if the test would be passing
138 # after the events are processed.
139 plan => 2, # Plan, either a number, undef, 'SKIP', or 'NO PLAN'
141 follows_plan => 1, # True if there is a plan and it was followed.
142 # False if the plan and assertions did not
143 # match, undef if no plan was present in the
144 # event list.
145 bailed_out => undef, # undef unless there was a bail-out in the
147 # events in which case this will be a string
148 # explaining why there was a bailout, if no
149 # reason was given this will simply be set to
150 # true (1).
151 skip_reason => undef, # If there was a skip_all this will give the
153 # reason.
154 }
155 $new = $events->upgrade
157 $events->upgrade(in_place => $BOOL)
158 Note: This normally returns a new instance, leaving the original
159 unchanged. If you call it in void context it will throw an
160 exception. If you want to modify the original you must pass in the
161 "in_place => 1" option. You may call this in void context when you
162 ask to modify it in place. The in-place form returns the instance
163 that was modified so you can chain methods.
164 This will create a clone of the list where all events have been
166 converted into Test2::API::InterceptResult::Event instances. This
167 is extremely helpful as Test2::API::InterceptResult::Event provide
168 a much better interface for working with events. This allows you to
169 avoid thinking about legacy event types.
170 This also means your tests against the list are not fragile if the
172 tool you are testing randomly changes what type of events it
173 generates (IE Changing from Test2::Event::Ok to Test2::Event::Pass,
174 both make assertions and both will normalize to identical (or close
175 enough) Test2::API::InterceptResult::Event instances.
176 Really you almost always want this, the only reason it is not done
178 automatically is to make sure the intercept() tool is backwards
179 compatible.
180 $new = $events->squash_info
182 $events->squash_info(in_place => $BOOL)
183 Note: This normally returns a new instance, leaving the original
184 unchanged. If you call it in void context it will throw an
185 exception. If you want to modify the original you must pass in the
186 "in_place => 1" option. You may call this in void context when you
187 ask to modify it in place. The in-place form returns the instance
188 that was modified so you can chain methods.
189 Note: All events in the new or modified instance will be converted
191 to Test2::API::InterceptResult::Event instances. There is no way to
192 avoid this, the squash operation requires the upgraded event class.
193 Test::More and many other legacy tools would send notes, diags, and
195 assertions as seperate events. A subtest in Test::More would send a
196 note with the subtest name, the subtest assertion, and finally a
197 diagnostics event if the subtest failed. This method will normalize
198 things by squashing the note and diag into the same event as the
199 subtest (This is different from putting them into the subtest,
200 which is not what happens).
201 FILTERING
203 Note: These normally return new instances, leaving the originals
204 unchanged. If you call them in void context they will throw
205 exceptions. If you want to modify the originals you must pass in the
206 "in_place => 1" option. You may call these in void context when you ask
207 to modify them in place. The in-place forms return the instance that
208 was modified so you can chain methods.
209 %PARAMS
211 These all accept the same 2 optional parameters:
213 in_place => $BOOL
215 When true the method will modify the instance in place instead of
216 returning a new instance.
217 args => \@ARGS
219 If you wish to pass parameters into the event method being used for
220 filtering, you may do so here.
221 METHODS
223 $events->grep($CALL, %PARAMS)
225 This is essentially:
226 Test2::API::InterceptResult->new(
228 grep { $_->$CALL( @{$PARAMS{args}} ) } $self->event_list,
229 );
230 Note: that $CALL is called on an upgraded version of the event,
232 though the events returned will be the original ones, not the
233 upgraded ones.
234 $CALL may be either the name of a method on
236 Test2::API::InterceptResult::Event, or a coderef.
237 $events->asserts(%PARAMS)
239 This is essentially:
240 $events->grep(has_assert => @{$PARAMS{args}})
242 It returns a new instance containing only the events that made
244 assertions.
245 $events->subtests(%PARAMS)
247 This is essentially:
248 $events->grep(has_subtest => @{$PARAMS{args}})
250 It returns a new instance containing only the events that have
252 subtests.
253 $events->diags(%PARAMS)
255 This is essentially:
256 $events->grep(has_diags => @{$PARAMS{args}})
258 It returns a new instance containing only the events that have
260 diags.
261 $events->notes(%PARAMS)
263 This is essentially:
264 $events->grep(has_notes => @{$PARAMS{args}})
266 It returns a new instance containing only the events that have
268 notes.
269 $events->errors(%PARAMS)
271 Note: Errors are NOT failing assertions. Failing assertions are a
272 different thing.
273 This is essentially:
275 $events->grep(has_errors => @{$PARAMS{args}})
277 It returns a new instance containing only the events that have
279 errors.
280 $events->plans(%PARAMS)
282 This is essentially:
283 $events->grep(has_plan => @{$PARAMS{args}})
285 It returns a new instance containing only the events that set the
287 plan.
288 $events->causes_fail(%PARAMS)
290 $events->causes_failure(%PARAMS)
291 These are essentially:
292 $events->grep(causes_fail => @{$PARAMS{args}})
294 $events->grep(causes_failure => @{$PARAMS{args}})
295 Note: causes_fail() and causes_failure() are both aliases for
297 eachother in events, so these methods are effectively aliases here
298 as well.
299 It returns a new instance containing only the events that cause
301 failure.
302 MAPPING
304 These methods ALWAYS return an arrayref.
305 Note: No methods on Test2::API::InterceptResult::Event alter the event
307 in any way.
308 Important Notes about Events:
310 Test2::API::InterceptResult::Event was tailor-made to be used in event-
312 lists. Most methods that are not applicable to a given event will
313 return an empty list, so you normally do not need to worry about
314 unwanted "undef" values or exceptions being thrown. Mapping over event
315 methods is an entended use, so it works well to produce lists.
316 Exceptions to the rule:
318 Some methods such as "causes_fail" always return a boolean true or
320 false for all events. Any method prefixed with "the_" conveys the
321 intent that the event should have exactly 1 of something, so those will
322 throw an exception when that condition is not true.
323 $arrayref = $events->map($CALL, %PARAMS)
325 This is essentially:
326 [ map { $_->$CALL(@{ $PARAMS{args} }) } $events->upgrade->event_list ];
328 $CALL may be either the name of a method on
330 Test2::API::InterceptResult::Event, or a coderef.
331 $arrayref = $events->flatten(%PARAMS)
333 This is essentially:
334 [ map { $_->flatten(@{ $PARAMS{args} }) } $events->upgrade->event_list ];
336 It returns a new list of flattened structures.
338 See Test2::API::InterceptResult::Event for details on what
340 flatten() returns.
341 $arrayref = $events->briefs(%PARAMS)
343 This is essentially:
344 [ map { $_->briefs(@{ $PARAMS{args} }) } $events->upgrade->event_list ];
346 It returns a new list of event briefs.
348 See Test2::API::InterceptResult::Event for details on what brief()
350 returns.
351 $arrayref = $events->summaries(%PARAMS)
353 This is essentially:
354 [ map { $_->summaries(@{ $PARAMS{args} }) } $events->upgrade->event_list ];
356 It returns a new list of event summaries.
358 See Test2::API::InterceptResult::Event for details on what
360 summary() returns.
361 $arrayref = $events->subtest_results(%PARAMS)
363 This is essentially:
364 [ map { $_->subtest_result(@{ $PARAMS{args} }) } $events->upgrade->event_list ];
366 It returns a new list of event summaries.
368 See Test2::API::InterceptResult::Event for details on what
370 subtest_result() returns.
371 $arrayref = $events->diag_messages(%PARAMS)
373 This is essentially:
374 [ map { $_->diag_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];
376 It returns a new list of diagnostic messages (strings).
378 See Test2::API::InterceptResult::Event for details on what
380 diag_messages() returns.
381 $arrayref = $events->note_messages(%PARAMS)
383 This is essentially:
384 [ map { $_->note_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];
386 It returns a new list of notification messages (strings).
388 See Test2::API::InterceptResult::Event for details on what
390 note_messages() returns.
391 $arrayref = $events->error_messages(%PARAMS)
393 This is essentially:
394 [ map { $_->error_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];
396 It returns a new list of error messages (strings).
398 See Test2::API::InterceptResult::Event for details on what
400 error_messages() returns.
401
403 The source code repository for Test2 can be found at
404 http://github.com/Test-More/test-more/.
405
407 Chad Granum <exodist@cpan.org>
408
410 Chad Granum <exodist@cpan.org>
411
413 Copyright 2020 Chad Granum <exodist@cpan.org>.
414 This program is free software; you can redistribute it and/or modify it
416 under the same terms as Perl itself.
417 See http://dev.perl.org/licenses/
419perl v5.38.0 2023-07-21 Test2::API::InterceptResult(3)