Debian Codegraph @

upstream/debian-unstable/man3/Test2::Event.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Test2::Event 3perl"
58 .TH Test2::Event 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test2::Event \- Base class for events
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 Base class for all event objects that get passed through
68 Test2.
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 3
72 \& package Test2::Event::MyEvent;
73 \& use strict;
74 \& use warnings;
75 \&
76 \& # This will make our class an event subclass (required)
77 \& use base \*(AqTest2::Event\*(Aq;
78 \&
79 \& # Add some accessors (optional)
80 \& # You are not obligated to use HashBase, you can use any object tool you
81 \& # want, or roll your own accessors.
82 \& use Test2::Util::HashBase qw/foo bar baz/;
83 \&
84 \& # Use this if you want the legacy API to be written for you, for this to
85 \& # work you will need to implement a facet_data() method.
86 \& use Test2::Util::Facets2Legacy;
87 \&
88 \& # Chance to initialize some defaults
89 \& sub init {
90 \& my $self = shift;
91 \& # no other args in @_
92 \&
93 \& $self\->set_foo(\*(Aqxxx\*(Aq) unless defined $self\->foo;
94 \&
95 \& ...
96 \& }
97 \&
98 \& # This is the new way for events to convey data to the Test2 system
99 \& sub facet_data {
100 \& my $self = shift;
101 \&
102 \& # Get common facets such as \*(Aqabout\*(Aq, \*(Aqtrace\*(Aq \*(Aqamnesty\*(Aq, and \*(Aqmeta\*(Aq
103 \& my $facet_data = $self\->common_facet_data();
104 \&
105 \& # Are you making an assertion?
106 \& $facet_data\->{assert} = {pass => 1, details => \*(Aqmy assertion\*(Aq};
107 \& ...
108 \&
109 \& return $facet_data;
110 \& }
111 \&
112 \& 1;
113 .Ve
114 .SH METHODS
115 .IX Header "METHODS"
116 .SS GENERAL
117 .IX Subsection "GENERAL"
118 .ie n .IP "$trace = $e\->trace" 4
119 .el .IP "\f(CW$trace\fR = \f(CW$e\fR\->trace" 4
120 .IX Item "$trace = $e->trace"
121 Get a snapshot of the Test2::EventFacet::Trace as it was when this event was
122 generated
123 .ie n .IP "$bool_or_undef = $e\->related($e2)" 4
124 .el .IP "\f(CW$bool_or_undef\fR = \f(CW$e\fR\->related($e2)" 4
125 .IX Item "$bool_or_undef = $e->related($e2)"
126 Check if 2 events are related. In this case related means their traces share a
127 signature meaning they were created with the same context (or at the very least
128 by contexts which share an id, which is the same thing unless someone is doing
129 something very bad).
130 .Sp
131 This can be used to reliably link multiple events created by the same tool. For
132 instance a failing test like \f(CW\*(C`ok(0, "fail"\*(C'\fR will generate 2 events, one being
133 a Test2::Event::Ok, the other being a Test2::Event::Diag, both of these
134 events are related having been created under the same context and by the same
135 initial tool (though multiple tools may have been nested under the initial
136 one).
137 .Sp
138 This will return \f(CW\*(C`undef\*(C'\fR if the relationship cannot be checked, which happens
139 if either event has an incomplete or missing trace. This will return \f(CW0\fR if
140 the traces are complete, but do not match. \f(CW1\fR will be returned if there is a
141 match.
142 .ie n .IP "$e\->add_amnesty({tag => $TAG, details => $DETAILS});" 4
143 .el .IP "\f(CW$e\fR\->add_amnesty({tag => \f(CW$TAG\fR, details => \f(CW$DETAILS\fR});" 4
144 .IX Item "$e->add_amnesty({tag => $TAG, details => $DETAILS});"
145 This can be used to add amnesty to this event. Amnesty only effects failing
146 assertions in most cases, but some formatters may display them for passing
147 assertions, or even non-assertions as well.
148 .Sp
149 Amnesty will prevent a failed assertion from causing the overall test to fail.
150 In other words it marks a failure as expected and allowed.
151 .Sp
152 \&\fBNote:\fR This is how 'TODO' is implemented under the hood. TODO is essentially
153 amnesty with the 'TODO' tag. The details are the reason for the TODO.
154 .ie n .IP "$uuid = $e\->uuid" 4
155 .el .IP "\f(CW$uuid\fR = \f(CW$e\fR\->uuid" 4
156 .IX Item "$uuid = $e->uuid"
157 If UUID tagging is enabled (See Test::API) then any event that has made its
158 way through a hub will be tagged with a UUID. A newly created event will not
159 yet be tagged in most cases.
160 .ie n .IP "$class = $e\->load_facet($name)" 4
161 .el .IP "\f(CW$class\fR = \f(CW$e\fR\->load_facet($name)" 4
162 .IX Item "$class = $e->load_facet($name)"
163 This method is used to load a facet by name (or key). It will attempt to load
164 the facet class, if it succeeds it will return the class it loaded. If it fails
165 it will return \f(CW\*(C`undef\*(C'\fR. This caches the result at the class level so that
166 future calls will be faster.
167 .Sp
168 The \f(CW$name\fR variable should be the key used to access the facet in a facets
169 hashref. For instance the assertion facet has the key 'assert', the information
170 facet has the 'info' key, and the error facet has the key 'errors'. You may
171 include or omit the 's' at the end of the name, the method is smart enough to
172 try both the 's' and no\-'s' forms, it will check what you provided first, and
173 if that is not found it will add or strip the 's and try again.
174 .ie n .IP "@classes = $e\->\fBFACET_TYPES()\fR" 4
175 .el .IP "\f(CW@classes\fR = \f(CW$e\fR\->\fBFACET_TYPES()\fR" 4
176 .IX Item "@classes = $e->FACET_TYPES()"
177 .PD 0
178 .ie n .IP "@classes = Test2::Event\->\fBFACET_TYPES()\fR" 4
179 .el .IP "\f(CW@classes\fR = Test2::Event\->\fBFACET_TYPES()\fR" 4
180 .IX Item "@classes = Test2::Event->FACET_TYPES()"
181 .PD
182 This returns a list of all facets that have been loaded using the
183 \&\f(CWload_facet()\fR method. This will not return any classes that have not been
184 loaded, or have been loaded directly without a call to \f(CWload_facet()\fR.
185 .Sp
186 \&\fBNote:\fR The core facet types are automatically loaded and populated in this
187 list.
188 .SS "NEW API"
189 .IX Subsection "NEW API"
190 .ie n .IP "$hashref = $e\->\fBcommon_facet_data()\fR;" 4
191 .el .IP "\f(CW$hashref\fR = \f(CW$e\fR\->\fBcommon_facet_data()\fR;" 4
192 .IX Item "$hashref = $e->common_facet_data();"
193 This can be used by subclasses to generate a starting facet data hashref. This
194 will populate the hashref with the trace, meta, amnesty, and about facets.
195 These facets are nearly always produced the same way for all events.
196 .ie n .IP "$hashref = $e\->\fBfacet_data()\fR" 4
197 .el .IP "\f(CW$hashref\fR = \f(CW$e\fR\->\fBfacet_data()\fR" 4
198 .IX Item "$hashref = $e->facet_data()"
199 If you do not override this then the default implementation will attempt to
200 generate facets from the legacy API. This generation is limited only to what
201 the legacy API can provide. It is recommended that you override this method and
202 write out explicit facet data.
203 .ie n .IP "$hashref = $e\->\fBfacets()\fR" 4
204 .el .IP "\f(CW$hashref\fR = \f(CW$e\fR\->\fBfacets()\fR" 4
205 .IX Item "$hashref = $e->facets()"
206 This takes the hashref from \f(CWfacet_data()\fR and blesses each facet into the
207 proper \f(CW\*(C`Test2::EventFacet::*\*(C'\fR subclass. If no class can be found for any given
208 facet it will be passed along unchanged.
209 .ie n .IP "@errors = $e\->\fBvalidate_facet_data()\fR;" 4
210 .el .IP "\f(CW@errors\fR = \f(CW$e\fR\->\fBvalidate_facet_data()\fR;" 4
211 .IX Item "@errors = $e->validate_facet_data();"
212 .PD 0
213 .ie n .IP "@errors = $e\->validate_facet_data(%params);" 4
214 .el .IP "\f(CW@errors\fR = \f(CW$e\fR\->validate_facet_data(%params);" 4
215 .IX Item "@errors = $e->validate_facet_data(%params);"
216 .ie n .IP "@errors = $e\->validate_facet_data(\e%facets, %params);" 4
217 .el .IP "\f(CW@errors\fR = \f(CW$e\fR\->validate_facet_data(\e%facets, \f(CW%params\fR);" 4
218 .IX Item "@errors = $e->validate_facet_data(%facets, %params);"
219 .ie n .IP "@errors = Test2::Event\->validate_facet_data(%params);" 4
220 .el .IP "\f(CW@errors\fR = Test2::Event\->validate_facet_data(%params);" 4
221 .IX Item "@errors = Test2::Event->validate_facet_data(%params);"
222 .ie n .IP "@errors = Test2::Event\->validate_facet_data(\e%facets, %params);" 4
223 .el .IP "\f(CW@errors\fR = Test2::Event\->validate_facet_data(\e%facets, \f(CW%params\fR);" 4
224 .IX Item "@errors = Test2::Event->validate_facet_data(%facets, %params);"
225 .PD
226 This method will validate facet data and return a list of errors. If no errors
227 are found this will return an empty list.
228 .Sp
229 This can be called as an object method with no arguments, in which case the
230 \&\f(CWfacet_data()\fR method will be called to get the facet data to be validated.
231 .Sp
232 When used as an object method the \f(CW\*(C`\e%facet_data\*(C'\fR argument may be omitted.
233 .Sp
234 When used as a class method the \f(CW\*(C`\e%facet_data\*(C'\fR argument is required.
235 .Sp
236 Remaining arguments will be slurped into a \f(CW%params\fR hash.
237 .Sp
238 Currently only 1 parameter is defined:
239 .RS 4
240 .ie n .IP "require_facet_class => $BOOL" 4
241 .el .IP "require_facet_class => \f(CW$BOOL\fR" 4
242 .IX Item "require_facet_class => $BOOL"
243 When set to true (default is false) this will reject any facets where a facet
244 class cannot be found. Normally facets without classes are assumed to be custom
245 and are ignored.
246 .RE
247 .RS 4
248 .RE
249 .PP
250 \fIWHAT ARE FACETS?\fR
251 .IX Subsection "WHAT ARE FACETS?"
252 .PP
253 Facets are how events convey their purpose to the Test2 internals and
254 formatters. An event without facets will have no intentional effect on the
255 overall test state, and will not be displayed at all by most formatters, except
256 perhaps to say that an event of an unknown type was seen.
257 .PP
258 Facets are produced by the \f(CWfacet_data()\fR subroutine, which you should
259 nearly-always override. \f(CWfacet_data()\fR is expected to return a hashref where
260 each key is the facet type, and the value is either a hashref with the data for
261 that facet, or an array of hashrefs. Some facets must be defined as single
262 hashrefs, some must be defined as an array of hashrefs, No facets allow both.
263 .PP
264 \&\f(CWfacet_data()\fR \fBMUST NOT\fR bless the data it returns, the main hashref, and
265 nested facet hashrefs \fBMUST\fR be bare, though items contained within each
266 facet may be blessed. The data returned by this method \fBshould\fR also be copies
267 of the internal data in order to prevent accidental state modification.
268 .PP
269 \&\f(CWfacets()\fR takes the data from \f(CWfacet_data()\fR and blesses it into the
270 \&\f(CW\*(C`Test2::EventFacet::*\*(C'\fR packages. This is rarely used however, the EventFacet
271 packages are primarily for convenience and documentation. The EventFacet
272 classes are not used at all internally, instead the raw data is used.
273 .PP
274 Here is a list of facet types by package. The packages are not used internally,
275 but are where the documentation for each type is kept.
276 .PP
277 \&\fBNote:\fR Every single facet type has the \f(CW\*(Aqdetails\*(Aq\fR field. This field is
278 always intended for human consumption, and when provided, should explain the
279 \&'why' for the facet. All other fields are facet specific.
280 .IP "about => {...}" 4
281 .IX Item "about => {...}"
282 Test2::EventFacet::About
283 .Sp
284 This contains information about the event itself such as the event package
285 name. The \f(CW\*(C`details\*(C'\fR field for this facet is an overall summary of the event.
286 .IP "assert => {...}" 4
287 .IX Item "assert => {...}"
288 Test2::EventFacet::Assert
289 .Sp
290 This facet is used if an assertion was made. The \f(CW\*(C`details\*(C'\fR field of this facet
291 is the description of the assertion.
292 .IP "control => {...}" 4
293 .IX Item "control => {...}"
294 Test2::EventFacet::Control
295 .Sp
296 This facet is used to tell the Test2::Event::Hub about special actions the
297 event causes. Things like halting all testing, terminating the current test,
298 etc. In this facet the \f(CW\*(C`details\*(C'\fR field explains why any special action was
299 taken.
300 .Sp
301 \&\fBNote:\fR This is how bail-out is implemented.
302 .IP "meta => {...}" 4
303 .IX Item "meta => {...}"
304 Test2::EventFacet::Meta
305 .Sp
306 The meta facet contains all the meta-data attached to the event. In this case
307 the \f(CW\*(C`details\*(C'\fR field has no special meaning, but may be present if something
308 sets the 'details' meta-key on the event.
309 .IP "parent => {...}" 4
310 .IX Item "parent => {...}"
311 Test2::EventFacet::Parent
312 .Sp
313 This facet contains nested events and similar details for subtests. In this
314 facet the \f(CW\*(C`details\*(C'\fR field will typically be the name of the subtest.
315 .IP "plan => {...}" 4
316 .IX Item "plan => {...}"
317 Test2::EventFacet::Plan
318 .Sp
319 This facet tells the system that a plan has been set. The \f(CW\*(C`details\*(C'\fR field of
320 this is usually left empty, but when present explains why the plan is what it
321 is, this is most useful if the plan is to skip-all.
322 .IP "trace => {...}" 4
323 .IX Item "trace => {...}"
324 Test2::EventFacet::Trace
325 .Sp
326 This facet contains information related to when and where the event was
327 generated. This is how the test file and line number of a failure is known.
328 This facet can also help you to tell if tests are related.
329 .Sp
330 In this facet the \f(CW\*(C`details\*(C'\fR field overrides the "failed at test_file.t line
331 42." message provided on assertion failure.
332 .IP "amnesty => [{...}, ...]" 4
333 .IX Item "amnesty => [{...}, ...]"
334 Test2::EventFacet::Amnesty
335 .Sp
336 The amnesty facet is a list instead of a single item, this is important as
337 amnesty can come from multiple places at once.
338 .Sp
339 For each instance of amnesty the \f(CW\*(C`details\*(C'\fR field explains why amnesty was
340 granted.
341 .Sp
342 \&\fBNote:\fR Outside of formatters amnesty only acts to forgive a failing
343 assertion.
344 .IP "errors => [{...}, ...]" 4
345 .IX Item "errors => [{...}, ...]"
346 Test2::EventFacet::Error
347 .Sp
348 The errors facet is a list instead of a single item, any number of errors can
349 be listed. In this facet \f(CW\*(C`details\*(C'\fR describes the error, or may contain the raw
350 error message itself (such as an exception). In perl exception may be blessed
351 objects, as such the raw data for this facet may contain nested items which are
352 blessed.
353 .Sp
354 Not all errors are considered fatal, there is a \f(CW\*(C`fail\*(C'\fR field that must be set
355 for an error to cause the test to fail.
356 .Sp
357 \&\fBNote:\fR This facet is unique in that the field name is 'errors' while the
358 package is 'Error'. This is because this is the only facet type that is both a
359 list, and has a name where the plural is not the same as the singular. This may
360 cause some confusion, but I feel it will be less confusing than the
361 alternative.
362 .IP "info => [{...}, ...]" 4
363 .IX Item "info => [{...}, ...]"
364 Test2::EventFacet::Info
365 .Sp
366 The 'info' facet is a list instead of a single item, any quantity of extra
367 information can be attached to an event. Some information may be critical
368 diagnostics, others may be simply commentary in nature, this is determined by
369 the \f(CW\*(C`debug\*(C'\fR flag.
370 .Sp
371 For this facet the \f(CW\*(C`details\*(C'\fR flag is the info itself. This info may be a
372 string, or it may be a data structure to display. This is one of the few facet
373 types that may contain blessed items.
374 .SS "LEGACY API"
375 .IX Subsection "LEGACY API"
376 .ie n .IP "$bool = $e\->causes_fail" 4
377 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->causes_fail" 4
378 .IX Item "$bool = $e->causes_fail"
379 Returns true if this event should result in a test failure. In general this
380 should be false.
381 .ie n .IP "$bool = $e\->increments_count" 4
382 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->increments_count" 4
383 .IX Item "$bool = $e->increments_count"
384 Should be true if this event should result in a test count increment.
385 .ie n .IP $e\->callback($hub) 4
386 .el .IP \f(CW$e\fR\->callback($hub) 4
387 .IX Item "$e->callback($hub)"
388 If your event needs to have extra effects on the Test2::Hub you can override
389 this method.
390 .Sp
391 This is called \fBBEFORE\fR your event is passed to the formatter.
392 .ie n .IP "$num = $e\->nested" 4
393 .el .IP "\f(CW$num\fR = \f(CW$e\fR\->nested" 4
394 .IX Item "$num = $e->nested"
395 If this event is nested inside of other events, this should be the depth of
396 nesting. (This is mainly for subtests)
397 .ie n .IP "$bool = $e\->global" 4
398 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->global" 4
399 .IX Item "$bool = $e->global"
400 Set this to true if your event is global, that is ALL threads and processes
401 should see it no matter when or where it is generated. This is not a common
402 thing to want, it is used by bail-out and skip_all to end testing.
403 .ie n .IP "$code = $e\->terminate" 4
404 .el .IP "\f(CW$code\fR = \f(CW$e\fR\->terminate" 4
405 .IX Item "$code = $e->terminate"
406 This is called \fBAFTER\fR your event has been passed to the formatter. This
407 should normally return undef, only change this if your event should cause the
408 test to exit immediately.
409 .Sp
410 If you want this event to cause the test to exit you should return the exit
411 code here. Exit code of 0 means exit success, any other integer means exit with
412 failure.
413 .Sp
414 This is used by Test2::Event::Plan to exit 0 when the plan is
415 \&'skip_all'. This is also used by Test2::Event:Bail to force the test
416 to exit with a failure.
417 .Sp
418 This is called after the event has been sent to the formatter in order to
419 ensure the event is seen and understood.
420 .ie n .IP "$msg = $e\->summary" 4
421 .el .IP "\f(CW$msg\fR = \f(CW$e\fR\->summary" 4
422 .IX Item "$msg = $e->summary"
423 This is intended to be a human readable summary of the event. This should
424 ideally only be one line long, but you can use multiple lines if necessary. This
425 is intended for human consumption. You do not need to make it easy for machines
426 to understand.
427 .Sp
428 The default is to simply return the event package name.
429 .ie n .IP "($count, $directive, $reason) = $e\->\fBsets_plan()\fR" 4
430 .el .IP "($count, \f(CW$directive\fR, \f(CW$reason\fR) = \f(CW$e\fR\->\fBsets_plan()\fR" 4
431 .IX Item "($count, $directive, $reason) = $e->sets_plan()"
432 Check if this event sets the testing plan. It will return an empty list if it
433 does not. If it does set the plan it will return a list of 1 to 3 items in
434 order: Expected Test Count, Test Directive, Reason for directive.
435 .ie n .IP "$bool = $e\->diagnostics" 4
436 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->diagnostics" 4
437 .IX Item "$bool = $e->diagnostics"
438 True if the event contains diagnostics info. This is useful because a
439 non-verbose harness may choose to hide events that are not in this category.
440 Some formatters may choose to send these to STDERR instead of STDOUT to ensure
441 they are seen.
442 .ie n .IP "$bool = $e\->no_display" 4
443 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->no_display" 4
444 .IX Item "$bool = $e->no_display"
445 False by default. This will return true on events that should not be displayed
446 by formatters.
447 .ie n .IP "$id = $e\->in_subtest" 4
448 .el .IP "\f(CW$id\fR = \f(CW$e\fR\->in_subtest" 4
449 .IX Item "$id = $e->in_subtest"
450 If the event is inside a subtest this should have the subtest ID.
451 .ie n .IP "$id = $e\->subtest_id" 4
452 .el .IP "\f(CW$id\fR = \f(CW$e\fR\->subtest_id" 4
453 .IX Item "$id = $e->subtest_id"
454 If the event is a final subtest event, this should contain the subtest ID.
455 .SH "THIRD PARTY META-DATA"
456 .IX Header "THIRD PARTY META-DATA"
457 This object consumes Test2::Util::ExternalMeta which provides a consistent
458 way for you to attach meta-data to instances of this class. This is useful for
459 tools, plugins, and other extensions.
460 .SH SOURCE
461 .IX Header "SOURCE"
462 The source code repository for Test2 can be found at
463 <https://github.com/Test\-More/test\-more/>.
464 .SH MAINTAINERS
465 .IX Header "MAINTAINERS"
466 .IP "Chad Granum <[email protected]>" 4
467 .IX Item "Chad Granum <[email protected]>"
468 .SH AUTHORS
469 .IX Header "AUTHORS"
470 .PD 0
471 .IP "Chad Granum <[email protected]>" 4
472 .IX Item "Chad Granum <[email protected]>"
473 .PD
474 .SH COPYRIGHT
475 .IX Header "COPYRIGHT"
476 Copyright 2020 Chad Granum <[email protected]>.
477 .PP
478 This program is free software; you can redistribute it and/or
479 modify it under the same terms as Perl itself.
480 .PP
481 See <https://dev.perl.org/licenses/>