1Test2::Event(3) User Contributed Perl Documentation Test2::Event(3)
2
6 Test2::Event - Base class for events
7
9 Base class for all event objects that get passed through Test2.
10
12 package Test2::Event::MyEvent;
13 use strict;
14 use warnings;
15 # This will make our class an event subclass (required)
17 use base 'Test2::Event';
18 # 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 # 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 # Chance to initialize some defaults
29 sub init {
30 my $self = shift;
31 # no other args in @_
32 $self->set_foo('xxx') unless defined $self->foo;
34 ...
36 }
37 # This is the new way for events to convey data to the Test2 system
39 sub facet_data {
40 my $self = shift;
41 # Get common facets such as 'about', 'trace' 'amnesty', and 'meta'
43 my $facet_data = $self->common_facet_data();
44 # Are you making an assertion?
46 $facet_data->{assert} = {pass => 1, details => 'my assertion'};
47 ...
48 return $facet_data;
50 }
51 1;
53
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 $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 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 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 $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 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 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 $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 $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 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 @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 Note: The core facet types are automatically loaded and populated
118 in this list.
119 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 $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 $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 @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 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 When used as an object method the "\%facet_data" argument may be
151 omitted.
152 When used as a class method the "\%facet_data" argument is
154 required.
155 Remaining arguments will be slurped into a %params hash.
157 Currently only 1 parameter is defined:
159 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 WHAT ARE FACETS?
166 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 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 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 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 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 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 about => {...}
200 Test2::EventFacet::About
201 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 assert => {...}
207 Test2::EventFacet::Assert
208 This facet is used if an assertion was made. The "details" field of
210 this facet is the description of the assertion.
211 control => {...}
213 Test2::EventFacet::Control
214 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 Note: This is how bail-out is implemented.
221 meta => {...}
223 Test2::EventFacet::Meta
224 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 parent => {...}
230 Test2::EventFacet::Parent
231 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 plan => {...}
237 Test2::EventFacet::Plan
238 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 trace => {...}
245 Test2::EventFacet::Trace
246 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 In this facet the "details" field overrides the "failed at
253 test_file.t line 42." message provided on assertion failure.
254 amnesty => [{...}, ...]
256 Test2::EventFacet::Amnesty
257 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 For each instance of amnesty the "details" field explains why
262 amnesty was granted.
263 Note: Outside of formatters amnesty only acts to forgive a failing
265 assertion.
266 errors => [{...}, ...]
268 Test2::EventFacet::Error
269 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 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 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 info => [{...}, ...]
286 Test2::EventFacet::Info
287 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 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 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 $bool = $e->increments_count
303 Should be true if this event should result in a test count
304 increment.
305 $e->callback($hub)
307 If your event needs to have extra effects on the Test2::Hub you can
308 override this method.
309 This is called BEFORE your event is passed to the formatter.
311 $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 $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 $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 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 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 This is called after the event has been sent to the formatter in
336 order to ensure the event is seen and understood.
337 $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 The default is to simply return the event package name.
345 ($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 $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 $bool = $e->no_display
359 False by default. This will return true on events that should not
360 be displayed by formatters.
361 $id = $e->in_subtest
363 If the event is inside a subtest this should have the subtest ID.
364 $id = $e->subtest_id
366 If the event is a final subtest event, this should contain the
367 subtest ID.
368
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
375 The source code repository for Test2 can be found at
376 http://github.com/Test-More/test-more/.
377
379 Chad Granum <exodist@cpan.org>
380
382 Chad Granum <exodist@cpan.org>
383
385 Copyright 2020 Chad Granum <exodist@cpan.org>.
386 This program is free software; you can redistribute it and/or modify it
388 under the same terms as Perl itself.
389 See http://dev.perl.org/licenses/
391perl v5.38.0 2023-07-21 Test2::Event(3)