1Test2::Event(3)       User Contributed Perl Documentation      Test2::Event(3)
2
3
4

NAME

6       Test2::Event - Base class for events
7

DESCRIPTION

9       Base class for all event objects that get passed through Test2.
10

SYNOPSIS

12           package Test2::Event::MyEvent;
13           use strict;
14           use warnings;
15
16           # This will make our class an event subclass (required)
17           use base 'Test2::Event';
18
19           # Add some accessors (optional)
20           # You are not obligated to use HashBase, you can use any object tool you
21           # want, or roll your own accessors.
22           use Test2::Util::HashBase qw/foo bar baz/;
23
24           # Use this if you want the legacy API to be written for you, for this to
25           # work you will need to implement a facet_data() method.
26           use Test2::Util::Facets2Legacy;
27
28           # Chance to initialize some defaults
29           sub init {
30               my $self = shift;
31               # no other args in @_
32
33               $self->set_foo('xxx') unless defined $self->foo;
34
35               ...
36           }
37
38           # This is the new way for events to convey data to the Test2 system
39           sub facet_data {
40               my $self = shift;
41
42               # Get common facets such as 'about', 'trace' 'amnesty', and 'meta'
43               my $facet_data = $self->common_facet_data();
44
45               # Are you making an assertion?
46               $facet_data->{assert} = {pass => 1, details => 'my assertion'};
47               ...
48
49               return $facet_data;
50           }
51
52           1;
53

METHODS

55   GENERAL
56       $trace = $e->trace
57           Get a snapshot of the Test2::EventFacet::Trace as it was when this
58           event was generated
59
60       $bool_or_undef = $e->related($e2)
61           Check if 2 events are related. In this case related means their
62           traces share a signature meaning they were created with the same
63           context (or at the very least by contexts which share an id, which
64           is the same thing unless someone is doing something very bad).
65
66           This can be used to reliably link multiple events created by the
67           same tool. For instance a failing test like "ok(0, "fail"" will
68           generate 2 events, one being a Test2::Event::Ok, the other being a
69           Test2::Event::Diag, both of these events are related having been
70           created under the same context and by the same initial tool (though
71           multiple tools may have been nested under the initial one).
72
73           This will return "undef" if the relationship cannot be checked,
74           which happens if either event has an incomplete or missing trace.
75           This will return 0 if the traces are complete, but do not match. 1
76           will be returned if there is a match.
77
78       $e->add_amnesty({tag => $TAG, details => $DETAILS});
79           This can be used to add amnesty to this event. Amnesty only effects
80           failing assertions in most cases, but some formatters may display
81           them for passing assertions, or even non-assertions as well.
82
83           Amnesty will prevent a failed assertion from causing the overall
84           test to fail.  In other words it marks a failure as expected and
85           allowed.
86
87           Note: This is how 'TODO' is implemented under the hood. TODO is
88           essentially amnesty with the 'TODO' tag. The details are the reason
89           for the TODO.
90
91       $uuid = $e->uuid
92           If UUID tagging is enabled (See Test::API) then any event that has
93           made its way through a hub will be tagged with a UUID. A newly
94           created event will not yet be tagged in most cases.
95
96       $class = $e->load_facet($name)
97           This method is used to load a facet by name (or key). It will
98           attempt to load the facet class, if it succeeds it will return the
99           class it loaded. If it fails it will return "undef". This caches
100           the result at the class level so that future calls will be faster.
101
102           The $name variable should be the key used to access the facet in a
103           facets hashref. For instance the assertion facet has the key
104           'assert', the information facet has the 'info' key, and the error
105           facet has the key 'errors'. You may include or omit the 's' at the
106           end of the name, the method is smart enough to try both the 's' and
107           no-'s' forms, it will check what you provided first, and if that is
108           not found it will add or strip the 's and try again.
109
110       @classes = $e->FACET_TYPES()
111       @classes = Test2::Event->FACET_TYPES()
112           This returns a list of all facets that have been loaded using the
113           load_facet() method. This will not return any classes that have not
114           been loaded, or have been loaded directly without a call to
115           load_facet().
116
117           Note: The core facet types are automatically loaded and populated
118           in this list.
119
120   NEW API
121       $hashref = $e->common_facet_data();
122           This can be used by subclasses to generate a starting facet data
123           hashref. This will populate the hashref with the trace, meta,
124           amnesty, and about facets.  These facets are nearly always produced
125           the same way for all events.
126
127       $hashref = $e->facet_data()
128           If you do not override this then the default implementation will
129           attempt to generate facets from the legacy API. This generation is
130           limited only to what the legacy API can provide. It is recommended
131           that you override this method and write out explicit facet data.
132
133       $hashref = $e->facets()
134           This takes the hashref from facet_data() and blesses each facet
135           into the proper "Test2::EventFacet::*" subclass. If no class can be
136           found for any given facet it will be passed along unchanged.
137
138       @errors = $e->validate_facet_data();
139       @errors = $e->validate_facet_data(%params);
140       @errors = $e->validate_facet_data(\%facets, %params);
141       @errors = Test2::Event->validate_facet_data(%params);
142       @errors = Test2::Event->validate_facet_data(\%facets, %params);
143           This method will validate facet data and return a list of errors.
144           If no errors are found this will return an empty list.
145
146           This can be called as an object method with no arguments, in which
147           case the facet_data() method will be called to get the facet data
148           to be validated.
149
150           When used as an object method the "\%facet_data" argument may be
151           omitted.
152
153           When used as a class method the "\%facet_data" argument is
154           required.
155
156           Remaining arguments will be slurped into a %params hash.
157
158           Currently only 1 parameter is defined:
159
160           require_facet_class => $BOOL
161               When set to true (default is false) this will reject any facets
162               where a facet class cannot be found. Normally facets without
163               classes are assumed to be custom and are ignored.
164
165       WHAT ARE FACETS?
166
167       Facets are how events convey their purpose to the Test2 internals and
168       formatters. An event without facets will have no intentional effect on
169       the overall test state, and will not be displayed at all by most
170       formatters, except perhaps to say that an event of an unknown type was
171       seen.
172
173       Facets are produced by the facet_data() subroutine, which you should
174       nearly-always override. facet_data() is expected to return a hashref
175       where each key is the facet type, and the value is either a hashref
176       with the data for that facet, or an array of hashrefs. Some facets must
177       be defined as single hashrefs, some must be defined as an array of
178       hashrefs, No facets allow both.
179
180       facet_data() MUST NOT bless the data it returns, the main hashref, and
181       nested facet hashrefs MUST be bare, though items contained within each
182       facet may be blessed. The data returned by this method should also be
183       copies of the internal data in order to prevent accidental state
184       modification.
185
186       facets() takes the data from facet_data() and blesses it into the
187       "Test2::EventFacet::*" packages. This is rarely used however, the
188       EventFacet packages are primarily for convenience and documentation.
189       The EventFacet classes are not used at all internally, instead the raw
190       data is used.
191
192       Here is a list of facet types by package. The packages are not used
193       internally, but are where the documentation for each type is kept.
194
195       Note: Every single facet type has the 'details' field. This field is
196       always intended for human consumption, and when provided, should
197       explain the 'why' for the facet. All other fields are facet specific.
198
199       about => {...}
200           Test2::EventFacet::About
201
202           This contains information about the event itself such as the event
203           package name. The "details" field for this facet is an overall
204           summary of the event.
205
206       assert => {...}
207           Test2::EventFacet::Assert
208
209           This facet is used if an assertion was made. The "details" field of
210           this facet is the description of the assertion.
211
212       control => {...}
213           Test2::EventFacet::Control
214
215           This facet is used to tell the Test2::Event::Hub about special
216           actions the event causes. Things like halting all testing,
217           terminating the current test, etc. In this facet the "details"
218           field explains why any special action was taken.
219
220           Note: This is how bail-out is implemented.
221
222       meta => {...}
223           Test2::EventFacet::Meta
224
225           The meta facet contains all the meta-data attached to the event. In
226           this case the "details" field has no special meaning, but may be
227           present if something sets the 'details' meta-key on the event.
228
229       parent => {...}
230           Test2::EventFacet::Parent
231
232           This facet contains nested events and similar details for subtests.
233           In this facet the "details" field will typically be the name of the
234           subtest.
235
236       plan => {...}
237           Test2::EventFacet::Plan
238
239           This facet tells the system that a plan has been set. The "details"
240           field of this is usually left empty, but when present explains why
241           the plan is what it is, this is most useful if the plan is to skip-
242           all.
243
244       trace => {...}
245           Test2::EventFacet::Trace
246
247           This facet contains information related to when and where the event
248           was generated. This is how the test file and line number of a
249           failure is known.  This facet can also help you to tell if tests
250           are related.
251
252           In this facet the "details" field overrides the "failed at
253           test_file.t line 42." message provided on assertion failure.
254
255       amnesty => [{...}, ...]
256           Test2::EventFacet::Amnesty
257
258           The amnesty facet is a list instead of a single item, this is
259           important as amnesty can come from multiple places at once.
260
261           For each instance of amnesty the "details" field explains why
262           amnesty was granted.
263
264           Note: Outside of formatters amnesty only acts to forgive a failing
265           assertion.
266
267       errors => [{...}, ...]
268           Test2::EventFacet::Error
269
270           The errors facet is a list instead of a single item, any number of
271           errors can be listed. In this facet "details" describes the error,
272           or may contain the raw error message itself (such as an exception).
273           In perl exception may be blessed objects, as such the raw data for
274           this facet may contain nested items which are blessed.
275
276           Not all errors are considered fatal, there is a "fail" field that
277           must be set for an error to cause the test to fail.
278
279           Note: This facet is unique in that the field name is 'errors' while
280           the package is 'Error'. This is because this is the only facet type
281           that is both a list, and has a name where the plural is not the
282           same as the singular. This may cause some confusion, but I feel it
283           will be less confusing than the alternative.
284
285       info => [{...}, ...]
286           Test2::EventFacet::Info
287
288           The 'info' facet is a list instead of a single item, any quantity
289           of extra information can be attached to an event. Some information
290           may be critical diagnostics, others may be simply commentary in
291           nature, this is determined by the "debug" flag.
292
293           For this facet the "details" flag is the info itself. This info may
294           be a string, or it may be a data structure to display. This is one
295           of the few facet types that may contain blessed items.
296
297   LEGACY API
298       $bool = $e->causes_fail
299           Returns true if this event should result in a test failure. In
300           general this should be false.
301
302       $bool = $e->increments_count
303           Should be true if this event should result in a test count
304           increment.
305
306       $e->callback($hub)
307           If your event needs to have extra effects on the Test2::Hub you can
308           override this method.
309
310           This is called BEFORE your event is passed to the formatter.
311
312       $num = $e->nested
313           If this event is nested inside of other events, this should be the
314           depth of nesting. (This is mainly for subtests)
315
316       $bool = $e->global
317           Set this to true if your event is global, that is ALL threads and
318           processes should see it no matter when or where it is generated.
319           This is not a common thing to want, it is used by bail-out and
320           skip_all to end testing.
321
322       $code = $e->terminate
323           This is called AFTER your event has been passed to the formatter.
324           This should normally return undef, only change this if your event
325           should cause the test to exit immediately.
326
327           If you want this event to cause the test to exit you should return
328           the exit code here. Exit code of 0 means exit success, any other
329           integer means exit with failure.
330
331           This is used by Test2::Event::Plan to exit 0 when the plan is
332           'skip_all'. This is also used by Test2::Event:Bail to force the
333           test to exit with a failure.
334
335           This is called after the event has been sent to the formatter in
336           order to ensure the event is seen and understood.
337
338       $msg = $e->summary
339           This is intended to be a human readable summary of the event. This
340           should ideally only be one line long, but you can use multiple
341           lines if necessary. This is intended for human consumption. You do
342           not need to make it easy for machines to understand.
343
344           The default is to simply return the event package name.
345
346       ($count, $directive, $reason) = $e->sets_plan()
347           Check if this event sets the testing plan. It will return an empty
348           list if it does not. If it does set the plan it will return a list
349           of 1 to 3 items in order: Expected Test Count, Test Directive,
350           Reason for directive.
351
352       $bool = $e->diagnostics
353           True if the event contains diagnostics info. This is useful because
354           a non-verbose harness may choose to hide events that are not in
355           this category.  Some formatters may choose to send these to STDERR
356           instead of STDOUT to ensure they are seen.
357
358       $bool = $e->no_display
359           False by default. This will return true on events that should not
360           be displayed by formatters.
361
362       $id = $e->in_subtest
363           If the event is inside a subtest this should have the subtest ID.
364
365       $id = $e->subtest_id
366           If the event is a final subtest event, this should contain the
367           subtest ID.
368

THIRD PARTY META-DATA

370       This object consumes Test2::Util::ExternalMeta which provides a
371       consistent way for you to attach meta-data to instances of this class.
372       This is useful for tools, plugins, and other extensions.
373

SOURCE

375       The source code repository for Test2 can be found at
376       http://github.com/Test-More/test-more/.
377

MAINTAINERS

379       Chad Granum <exodist@cpan.org>
380

AUTHORS

382       Chad Granum <exodist@cpan.org>
383
385       Copyright 2020 Chad Granum <exodist@cpan.org>.
386
387       This program is free software; you can redistribute it and/or modify it
388       under the same terms as Perl itself.
389
390       See http://dev.perl.org/licenses/
391
392
393
394perl v5.36.0                      2023-03-15                   Test2::Event(3)
Impressum