1Test2::API::InterceptReUssuelrt:C:oEnvternitb(u3t)ed PerTlesDto2c:u:mAePnIt:a:tIinotnerceptResult::Event(3)
2
3
4

NAME

6       Test2::API::InterceptResult::Event - Representation of an event for use
7       in testing other test tools.
8

DESCRIPTION

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
14       This POD documents the methods of these events, which are mainly
15       provided for you to use when testing your test tools.
16

SYNOPSIS

18           use Test2::V0;
19           use Test2::API qw/intercept/;
20
21           my $events = intercept {
22               ok(1, "A passing assertion");
23               plan(1);
24           };
25
26           # 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
31           # Now we can get individual events in this form
32           my $assert = $events->[0];
33           my $plan   = $events->[1];
34
35           # 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
43                   name => 'A passing assertion',
44                   pass => 1,
45
46                   trace_file => 'xxx.t',
47                   trace_line => 5,
48                 },
49                 {
50                   causes_failure => 0,
51
52                   plan => 1,
53
54                   trace_file => 'xxx.t',
55                   trace_line => 6,
56                 },
57               ],
58               "Flattened both events and returned an arrayref of the results
59           );
60

METHODS

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
69       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
75       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
79   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
84       $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
89   DUPLICATION
90       $copy = $event->clone
91           Create a deep copy of the event. Modifying either event will not
92           effect the other.
93
94   CONDENSED MULTI-FACET DATA
95       $bool = $event->causes_failure
96       $bool = $event->causes_fail
97           These are both aliases of the same functionality.
98
99           This will always return either a true value, or a false value. This
100           never returns a list.
101
102           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
110       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
117           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
120           Possible briefs:
121
122               # From control facets
123               "BAILED OUT"
124               "BAILED OUT: $why"
125
126               # From error facets
127               "ERROR"
128               "ERROR: $message"
129               "ERROR: $partial_message [...]"
130               "ERRORS: $first_error_message [...]"
131
132               # From assert facets
133               "PASS"
134               "FAIL"
135               "PASS with amnesty"
136               "FAIL with amnesty"
137
138               # From plan facets
139               "PLAN $count"
140               "NO PLAN"
141               "SKIP ALL"
142               "SKIP ALL: $why"
143
144           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
148       $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
154           If there are no meaningful facets this will return an empty
155           hashref.
156
157           If given the 'include_subevents' parameter it will also include
158           subtest data:
159
160           Here is a list of EVERY possible field. If a field is not
161           applicable it will not be present.
162
163           always present
164                       causes_failure => 1,    # Always present
165
166           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
171           If an assertion is present
172                       pass => 0,
173                       name => "1 + 1 = 2, so math works",
174
175           If a plan is present:
176                       plan => $count_or_SKIP_ALL_or_NO_PLAN,
177
178           If amnesty facets are present
179               You get an array for each type that is present.
180
181                       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
186                       skip => ["This will format the main drive, do not run"],
187
188                       ... => ["Other amnesty"]
189
190           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
194                       diag => [
195                           "Test failed at Foo/Bar.pm line 42",
196                           "You forgot to tie your boots",
197                       ],
198
199                       note => ["Your boots are red"],
200
201                       ...  => ["Other info"],
202
203           If error facets are present
204               Always an arrayref
205
206                       error => [
207                           "non fatal error (does not cause test failure, just an FYI",
208                           "FATAL: This is a fatal error (causes failure)",
209                       ],
210
211                       # Errors can have alternative tags, but in practice are always 'error',
212                       # listing this for completeness.
213                       ... => [ ... ]
214
215           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
222                           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
228                           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
233                           skip_reason => "foo",   # If there was a skip_all this will give the
234                                                   # reason.
235                       },
236
237               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
242                       subevents => Test2::API::InterceptResult->new(@child_events)->flatten(...),
243
244           If a bail-out is being requested
245               If no reason was given this will be set to 1.
246
247                       bailed_out => "reason",
248
249       $hashref = $event->summary()
250           This returns a limited summary. See flatten(), which is usually a
251           better option.
252
253               {
254                   brief => $event->brief || '',
255
256                   causes_failure => $event->causes_failure,
257
258                   trace_line    => $event->trace_line,
259                   trace_file    => $event->trace_file,
260                   trace_tool    => $event->trace_subname,
261                   trace_details => $event->trace_details,
262
263                   facets => [ sort keys(%{$event->{+FACET_DATA}}) ],
264               }
265
266   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
274           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
278       $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
282           If you are correct and there is exactly one instance of the facet
283           it will always return the hashref.
284
285           If there are 0 instances of the facet this will reutrn undef, not
286           an empty list.
287
288           If there are more than 1 instance this will throw an exception
289           because your assumption was incorrect.
290
291   TRACE FACET
292       @list_of_facets = $event->trace
293           TODO
294
295       $undef_or_hashref = $event->the_trace
296           This returns the trace hashref, or undef if it is not present.
297
298       $undef_or_arrayref = $event->frame
299           If a trace is present, and has a caller frame, this will be an
300           arrayref:
301
302               [$package, $file, $line, $subname]
303
304           If the trace is not present, or has no caller frame this will
305           return undef.
306
307       $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
312       $undef_or_string = $event->trace_package
313           Same as "(caller())[0]", the first element of the trace frame.
314
315           Will be undef if not present.
316
317       $undef_or_string = $event->trace_file
318           Same as "(caller())[1]", the second element of the trace frame.
319
320           Will be undef if not present.
321
322       $undef_or_integer = $event->trace_line
323           Same as "(caller())[2]", the third element of the trace frame.
324
325           Will be undef if not present.
326
327       $undef_or_string = $event->trace_subname
328       $undef_or_string = $event->trace_tool
329           Aliases for the same thing
330
331           Same as "(caller($level))[4]", the fourth element of the trace
332           frame.
333
334           Will be undef if not present.
335
336       $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
342   ASSERT FACET
343       $bool = $event->has_assert
344           Returns true if the event has an assert facet, false if it does
345           not.
346
347       $undef_or_hashref = $event->the_assert
348           Returns the assert facet if present, undef if it is not.
349
350       @list_of_facets = $event->assert
351           TODO
352
353       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
357   SUBTESTS (PARENT FACET)
358       $bool = $event->has_subtest
359           True if a subetest is present in this event.
360
361       $undef_or_hashref = $event->the_subtest
362           Get the one subtest if present, otherwise undef.
363
364       @list_of_facets = $event->subtest
365           TODO
366
367       EMPTY_LIST_OR_OBJECT = $event->subtest_result
368           Returns an empty list if there is no subtest.
369
370           Get an instance of Test2::API::InterceptResult representing the
371           subtest.
372
373   CONTROL FACET (BAILOUT, ENCODING)
374       $bool = $event->has_bailout
375           True if there was a bailout
376
377       $undef_hashref = $event->the_bailout
378           Return the control facet if it requested a bailout.
379
380       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
384       EMPTY_LIST_OR_STRING = $event->bailout_brief
385           Get the brief of the balout if present.
386
387       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
391   PLAN FACET
392       TODO
393
394       $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
399   AMNESTY FACET (TODO AND SKIP)
400       TODO
401
402       $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
416   ERROR FACET (CAPTURED EXCEPTIONS)
417       TODO
418
419       $event->has_errors
420       $event->the_errors
421       $event->errors
422       $event->error_messages
423       $event->error_brief
424
425   INFO FACET (DIAG, NOTE)
426       TODO
427
428       $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

SOURCE

443       The source code repository for Test2 can be found at
444       http://github.com/Test-More/test-more/.
445

MAINTAINERS

447       Chad Granum <exodist@cpan.org>
448

AUTHORS

450       Chad Granum <exodist@cpan.org>
451
453       Copyright 2020 Chad Granum <exodist@cpan.org>.
454
455       This program is free software; you can redistribute it and/or modify it
456       under the same terms as Perl itself.
457
458       See http://dev.perl.org/licenses/
459
460
461
462perl v5.36.0                      2023-03-T1e5st2::API::InterceptResult::Event(3)
Impressum