1Test2::API::InterceptReUssuelrt:C:oEnvternitb(u3t)ed PerTlesDto2c:u:mAePnIt:a:tIinotnerceptResult::Event(3)
2
6 Test2::API::InterceptResult::Event - Representation of an event for use
7 in testing other test tools.
8
10 "intercept { ... }" from Test2::API returns an instance of
11 Test2::API::InterceptResult which is a blessed arrayref of
12 Test2::API::InterceptResult::Event objects.
13 This POD documents the methods of these events, which are mainly
15 provided for you to use when testing your test tools.
16
18 use Test2::V0;
19 use Test2::API qw/intercept/;
20 my $events = intercept {
22 ok(1, "A passing assertion");
23 plan(1);
24 };
25 # This will convert all events into instances of
27 # Test2::API::InterceptResult::Event. Until we do this they are the
28 # original Test::Event::* instances
29 $events->upgrade(in_place => 1);
30 # Now we can get individual events in this form
32 my $assert = $events->[0];
33 my $plan = $events->[1];
34 # Or we can operate on all events at once:
36 my $flattened = $events->flatten;
37 is(
38 $flattened,
39 [
40 {
41 causes_failure => 0,
42 name => 'A passing assertion',
44 pass => 1,
45 trace_file => 'xxx.t',
47 trace_line => 5,
48 },
49 {
50 causes_failure => 0,
51 plan => 1,
53 trace_file => 'xxx.t',
55 trace_line => 6,
56 },
57 ],
58 "Flattened both events and returned an arrayref of the results
59 );
60
62 !!! IMPORTANT NOTES ON DESIGN !!!
63 Please pay attention to what these return, many return a scalar when
64 applicable or an empty list when not (as opposed to undef). Many also
65 always return a list of 0 or more items. Some always return a scalar.
66 Note that none of the methods care about context, their behavior is
67 consistent regardless of scalar, list, or void context.
68 This was done because this class was specifically designed to be used
70 in a list and generate more lists in bulk operations. Sometimes in a
71 map you want nothing to show up for the event, and you do not want an
72 undef in its place. In general single event instances are not going to
73 be used alone, though that is allowed.
74 As a general rule any method prefixed with "the_" implies the event
76 should have exactly 1 of the specified item, and and exception will be
77 thrown if there are 0, or more than 1 of the item.
78 ATTRIBUTES
80 $hashref = $event->facet_data
81 This will return the facet data hashref, which is all Test2 cares
82 about for any given event.
83 $class = $event->result_class
85 This is normally Test2::API::InterceptResult. This is set at
86 construction so that subtest results can be turned into instances
87 of it on demand.
88 DUPLICATION
90 $copy = $event->clone
91 Create a deep copy of the event. Modifying either event will not
92 effect the other.
93 CONDENSED MULTI-FACET DATA
95 $bool = $event->causes_failure
96 $bool = $event->causes_fail
97 These are both aliases of the same functionality.
98 This will always return either a true value, or a false value. This
100 never returns a list.
101 This method may be relatively slow (still super fast) because it
103 determines pass or fail by creating an instance of Test2::Hub and
104 asking it to process the event, and then asks the hub for its
105 pass/fail state. This is slower than bulding in logic to do the
106 check, but it is more reliable as it will always tell you what the
107 hub thinks, so the logic will never be out of date relative to the
108 Test2 logic that actually cares.
109 STRING_OR_EMPTY_LIST = $event->brief
111 Not all events have a brief, some events are not rendered by the
112 formatter, others have no "brief" data worth seeing. When this is
113 the case an empty list is returned. This is done intentionally so
114 it can be used in a map operation without having "undef" being
115 included in the result.
116 When a brief can be generated it is always a single 1-line string,
118 and is returned as-is, not in a list.
119 Possible briefs:
121 # From control facets
123 "BAILED OUT"
124 "BAILED OUT: $why"
125 # From error facets
127 "ERROR"
128 "ERROR: $message"
129 "ERROR: $partial_message [...]"
130 "ERRORS: $first_error_message [...]"
131 # From assert facets
133 "PASS"
134 "FAIL"
135 "PASS with amnesty"
136 "FAIL with amnesty"
137 # From plan facets
139 "PLAN $count"
140 "NO PLAN"
141 "SKIP ALL"
142 "SKIP ALL: $why"
143 Note that only the first applicable brief is returned. This is
145 essnetially a poor-mans TAP that only includes facets that could
146 (but not necessarily do) cause a failure.
147 $hashref = $event->flatten
149 $hashref = $event->flatten(include_subevents => 1)
150 This ALWAYS returns a hashref. This puts all the most useful data
151 for the most interesting facets into a single hashref for easy
152 validation.
153 If there are no meaningful facets this will return an empty
155 hashref.
156 If given the 'include_subevents' parameter it will also include
158 subtest data:
159 Here is a list of EVERY possible field. If a field is not
161 applicable it will not be present.
162 always present
164 causes_failure => 1, # Always present
165 Present if the event has a trace facet
167 trace_line => 42,
168 trace_file => 'Foo/Bar.pm',
169 trace_details => 'Extra trace details', # usually not present
170 If an assertion is present
172 pass => 0,
173 name => "1 + 1 = 2, so math works",
174 If a plan is present:
176 plan => $count_or_SKIP_ALL_or_NO_PLAN,
177 If amnesty facets are present
179 You get an array for each type that is present.
180 todo => [ # Yes you could be under multiple todos, this will list them all.
182 "I will fix this later",
183 "I promise to fix these",
184 ],
185 skip => ["This will format the main drive, do not run"],
187 ... => ["Other amnesty"]
189 If Info (note/diag) facets are present
191 You get an arrayref for any that are present, the key is not
192 defined if they are not present.
193 diag => [
195 "Test failed at Foo/Bar.pm line 42",
196 "You forgot to tie your boots",
197 ],
198 note => ["Your boots are red"],
200 ... => ["Other info"],
202 If error facets are present
204 Always an arrayref
205 error => [
207 "non fatal error (does not cause test failure, just an FYI",
208 "FATAL: This is a fatal error (causes failure)",
209 ],
210 # Errors can have alternative tags, but in practice are always 'error',
212 # listing this for completeness.
213 ... => [ ... ]
214 Present if the event is a subtest
216 subtest => {
217 count => 2, # Number of assertions made
218 failed => 1, # Number of test failures seen
219 is_passing => 0, # Boolean, true if the test would be passing
220 # after the events are processed.
221 plan => 2, # Plan, either a number, undef, 'SKIP', or 'NO PLAN'
223 follows_plan => 1, # True if there is a plan and it was followed.
224 # False if the plan and assertions did not
225 # match, undef if no plan was present in the
226 # event list.
227 bailed_out => "foo", # if there was a bail-out in the
229 # events in this will be a string explaining
230 # why there was a bailout, if no reason was
231 # given this will simply be set to true (1).
232 skip_reason => "foo", # If there was a skip_all this will give the
234 # reason.
235 },
236 if "(include_subtest => 1)" was provided as a parameter then
238 the following will be included. This is the result of turning
239 all subtest child events into an Test2::API::InterceptResult
240 instance and calling the "flatten" method on it.
241 subevents => Test2::API::InterceptResult->new(@child_events)->flatten(...),
243 If a bail-out is being requested
245 If no reason was given this will be set to 1.
246 bailed_out => "reason",
248 $hashref = $event->summary()
250 This returns a limited summary. See flatten(), which is usually a
251 better option.
252 {
254 brief => $event->brief || '',
255 causes_failure => $event->causes_failure,
257 trace_line => $event->trace_line,
259 trace_file => $event->trace_file,
260 trace_tool => $event->trace_subname,
261 trace_details => $event->trace_details,
262 facets => [ sort keys(%{$event->{+FACET_DATA}}) ],
264 }
265 DIRECT ARBITRARY FACET ACCESS
267 @list_of_facets = $event->facet($name)
268 This always returns a list of 0 or more items. This fetches the
269 facet instances from the event. For facets like 'assert' this will
270 always return 0 or 1 item. For events like 'info' (diags, notes)
271 this will return 0 or more instances, once for each instance of the
272 facet.
273 These will be blessed into the proper Test2::EventFacet subclass.
275 If no subclass can be found it will be blessed as an
276 Test2::API::InterceptResult::Facet generic facet class.
277 $undef_or_facet = $event->the_facet($name)
279 If you know you will have exactly 1 instance of a facet you can
280 call this.
281 If you are correct and there is exactly one instance of the facet
283 it will always return the hashref.
284 If there are 0 instances of the facet this will reutrn undef, not
286 an empty list.
287 If there are more than 1 instance this will throw an exception
289 because your assumption was incorrect.
290 TRACE FACET
292 @list_of_facets = $event->trace
293 TODO
294 $undef_or_hashref = $event->the_trace
296 This returns the trace hashref, or undef if it is not present.
297 $undef_or_arrayref = $event->frame
299 If a trace is present, and has a caller frame, this will be an
300 arrayref:
301 [$package, $file, $line, $subname]
303 If the trace is not present, or has no caller frame this will
305 return undef.
306 $undef_or_string = $event->trace_details
308 This is usually undef, but occasionally has a string that overrides
309 the file/line number debugging a trace usually provides on test
310 failure.
311 $undef_or_string = $event->trace_package
313 Same as "(caller())[0]", the first element of the trace frame.
314 Will be undef if not present.
316 $undef_or_string = $event->trace_file
318 Same as "(caller())[1]", the second element of the trace frame.
319 Will be undef if not present.
321 $undef_or_integer = $event->trace_line
323 Same as "(caller())[2]", the third element of the trace frame.
324 Will be undef if not present.
326 $undef_or_string = $event->trace_subname
328 $undef_or_string = $event->trace_tool
329 Aliases for the same thing
330 Same as "(caller($level))[4]", the fourth element of the trace
332 frame.
333 Will be undef if not present.
335 $undef_or_string = $event->trace_signature
337 A string that is a unique signature for the trace. If a single
338 context generates multiple events they will all have the same
339 signature. This can be used to tie assertions and diagnostics sent
340 as seperate events together after the fact.
341 ASSERT FACET
343 $bool = $event->has_assert
344 Returns true if the event has an assert facet, false if it does
345 not.
346 $undef_or_hashref = $event->the_assert
348 Returns the assert facet if present, undef if it is not.
349 @list_of_facets = $event->assert
351 TODO
352 EMPTY_LIST_OR_STRING = $event->assert_brief
354 Returns a string giving a brief of the assertion if an assertion is
355 present. Returns an empty list if no assertion is present.
356 SUBTESTS (PARENT FACET)
358 $bool = $event->has_subtest
359 True if a subetest is present in this event.
360 $undef_or_hashref = $event->the_subtest
362 Get the one subtest if present, otherwise undef.
363 @list_of_facets = $event->subtest
365 TODO
366 EMPTY_LIST_OR_OBJECT = $event->subtest_result
368 Returns an empty list if there is no subtest.
369 Get an instance of Test2::API::InterceptResult representing the
371 subtest.
372 CONTROL FACET (BAILOUT, ENCODING)
374 $bool = $event->has_bailout
375 True if there was a bailout
376 $undef_hashref = $event->the_bailout
378 Return the control facet if it requested a bailout.
379 EMPTY_LIST_OR_HASHREF = $event->bailout
381 Get a list of 0 or 1 hashrefs. The hashref will be the control
382 facet if a bail-out was requested.
383 EMPTY_LIST_OR_STRING = $event->bailout_brief
385 Get the brief of the balout if present.
386 EMPTY_LIST_OR_STRING = $event->bailout_reason
388 Get the reason for the bailout, an empty string if no reason was
389 provided, or an empty list if there was no bailout.
390 PLAN FACET
392 TODO
393 $bool = $event->has_plan
395 $undef_or_hashref = $event->the_plan
396 @list_if_hashrefs = $event->plan
397 EMPTY_LIST_OR_STRING $event->plan_brief
398 AMNESTY FACET (TODO AND SKIP)
400 TODO
401 $event->has_amnesty
403 $event->the_amnesty
404 $event->amnesty
405 $event->amnesty_reasons
406 $event->has_todos
407 $event->todos
408 $event->todo_reasons
409 $event->has_skips
410 $event->skips
411 $event->skip_reasons
412 $event->has_other_amnesty
413 $event->other_amnesty
414 $event->other_amnesty_reasons
415 ERROR FACET (CAPTURED EXCEPTIONS)
417 TODO
418 $event->has_errors
420 $event->the_errors
421 $event->errors
422 $event->error_messages
423 $event->error_brief
424 INFO FACET (DIAG, NOTE)
426 TODO
427 $event->has_info
429 $event->the_info
430 $event->info
431 $event->info_messages
432 $event->has_diags
433 $event->diags
434 $event->diag_messages
435 $event->has_notes
436 $event->notes
437 $event->note_messages
438 $event->has_other_info
439 $event->other_info
440 $event->other_info_messages
441
443 The source code repository for Test2 can be found at
444 http://github.com/Test-More/test-more/.
445
447 Chad Granum <exodist@cpan.org>
448
450 Chad Granum <exodist@cpan.org>
451
453 Copyright 2020 Chad Granum <exodist@cpan.org>.
454 This program is free software; you can redistribute it and/or modify it
456 under the same terms as Perl itself.
457 See http://dev.perl.org/licenses/
459perl v5.36.0 2023-03-T1e5st2::API::InterceptResult::Event(3)