Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Manual::Anatomy::Event.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Manual::Anatomy::Event 3pm"
61 .TH Test2::Manual::Anatomy::Event 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Manual::Anatomy::Event \- The internals of events
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 Events are how tools affect global state, and pass information along to the
71 harness, or the human running the tests.
72 .SH HISTORY
73 .IX Header "HISTORY"
74 Before proceeding it is important that you know some history of events.
75 Initially there was an event API, and an event would implement the API to
76 produce an effect. This API proved to be lossy and inflexible. Recently the
77 \&\*(Aqfacet\*(Aq system was introduced, and makes up for the shortcoming and
78 inflexibility of the old API.
79 .PP
80 All events must still implement the old API, but that can be largely automated
81 if you use the facet system effectively. Likewise essential facets can often be
82 deduced from events that only implement the old API, though their information
83 maybe less complete.
84 .SH "THE EVENT OBJECT"
85 .IX Header "THE EVENT OBJECT"
86 All event objects must subclass Test2::Event. If you inherit from this base
87 class, and implement the old API properly, facets will be generated for you for
88 free. On the other hand you can inherit from this, and also import
89 Test2::Util::Facets2Legacy which will instead rely on your facet data, and
90 deduce the old API from them.
91 .PP
92 All new events \f(CW\*(C`MUST\*(C'\fR implement both APIs one way or the other. A common way
93 to do this is to simply implement both APIs directly in your event.
94 .PP
95 Here is a good template for a new event:
96 .PP
97 .Vb 3
98 \& package Test2::Event::Mine;
99 \& use strict;
100 \& use warnings;
101 \&
102 \& use parent \*(AqTest2::Event\*(Aq;
103 \& use Test2::Util::Facets2Legacy \*(Aq:ALL\*(Aq;
104 \&
105 \& sub facet_data {
106 \& my $self = shift;
107 \&
108 \& # Adds \*(Aqabout\*(Aq, \*(Aqamnesty\*(Aq, and \*(Aqtrace\*(Aq facets
109 \& my $out = $self\->common_facet_data;
110 \&
111 \& # Add any additional facets to the $out hashref
112 \& ...
113 \&
114 \& return $out;
115 \& }
116 \&
117 \& 1;
118 .Ve
119 .SH "THE FACET API"
120 .IX Header "THE FACET API"
121 The new API is a single method: \f(CWfacet_data()\fR. This method must return a
122 hashref where each key is specific to a facet type, and the value is either a
123 facet hashref, or an array of hashrefs. Some facets \f(CW\*(C`MUST\*(C'\fR be lone hashrefs,
124 others \f(CW\*(C`MUST\*(C'\fR be hashrefs inside an arrayref.
125 .PP
126 The \fIstandard\fR facet types are as follows:
127 .ie n .IP "assert => {details => $name, pass => $bool, no_debug => $bool, number => $maybe_int}" 4
128 .el .IP "assert => {details => \f(CW$name\fR, pass => \f(CW$bool\fR, no_debug => \f(CW$bool\fR, number => \f(CW$maybe_int\fR}" 4
129 .IX Item "assert => {details => $name, pass => $bool, no_debug => $bool, number => $maybe_int}"
130 Documented in Test2::EventFacet::Assert. An event may only have one.
131 .Sp
132 The \*(Aqdetails\*(Aq key is the name of the assertion.
133 .Sp
134 The \*(Aqpass\*(Aq key denotes a passing or failing assertion.
135 .Sp
136 The \*(Aqno_debug\*(Aq key tells any harness or formatter that diagnostics should not
137 be added automatically to a failing assertion (used when there are custom
138 diagnostics instead).
139 .Sp
140 The \*(Aqnumber\*(Aq key is for harness use, never set it yourself.
141 .ie n .IP "about => {details => $string, no_display => $bool, package => $pkg}" 4
142 .el .IP "about => {details => \f(CW$string\fR, no_display => \f(CW$bool\fR, package => \f(CW$pkg\fR}" 4
143 .IX Item "about => {details => $string, no_display => $bool, package => $pkg}"
144 Documented in Test2::EventFacet::About. An event may only have one.
145 .Sp
146 \&\*(Aqdetails\*(Aq is a human readable string describing the overall event.
147 .Sp
148 \&\*(Aqno_display\*(Aq means that a formatter/harness should hide the event.
149 .Sp
150 \&\*(Aqpackage\*(Aq is the package of the event the facet describes (IE: Test2::Event::Ok)
151 .ie n .IP "amnesty => [{details => $string, tag => $short_string, inherited => $bool}]" 4
152 .el .IP "amnesty => [{details => \f(CW$string\fR, tag => \f(CW$short_string\fR, inherited => \f(CW$bool\fR}]" 4
153 .IX Item "amnesty => [{details => $string, tag => $short_string, inherited => $bool}]"
154 Documented in Test2::EventFacet::Amnesty. An event may have multiple.
155 .Sp
156 This event is how things like \*(Aqtodo\*(Aq are implemented. Amnesty prevents a
157 failing assertion from causing a global test failure.
158 .Sp
159 \&\*(Aqdetails\*(Aq is a human readable description of why the failure is being granted
160 amnesty (IE The \*(Aqtodo\*(Aq reason)
161 .Sp
162 \&\*(Aqtag\*(Aq is a short human readable string, or category for the amnesty. This is
163 typically \*(AqTODO\*(Aq or \*(AqSKIP\*(Aq.
164 .Sp
165 \&\*(Aqinherited\*(Aq is true if the amnesty was applied in a parent context (true if
166 this test is run in a subtest that is marked todo).
167 .ie n .IP "control => {details => $string, global => $bool, terminate => $maybe_int, halt => $bool, has_callback => $bool, encoding => $enc}" 4
168 .el .IP "control => {details => \f(CW$string\fR, global => \f(CW$bool\fR, terminate => \f(CW$maybe_int\fR, halt => \f(CW$bool\fR, has_callback => \f(CW$bool\fR, encoding => \f(CW$enc\fR}" 4
169 .IX Item "control => {details => $string, global => $bool, terminate => $maybe_int, halt => $bool, has_callback => $bool, encoding => $enc}"
170 Documented in Test2::EventFacet::Control. An event may have one.
171 .Sp
172 This facet is used to apply extra behavior when the event is processed.
173 .Sp
174 \&\*(Aqdetails\*(Aq is a human readable explanation for the behavior.
175 .Sp
176 \&\*(Aqglobal\*(Aq true if this event should be forwarded to, and processed by, all hubs
177 everywhere. (bail\-out uses this)
178 .Sp
179 \&\*(Aqterminate\*(Aq this should either be undef, or an integer. When defined this will
180 cause the test to exit with the specific exit code.
181 .Sp
182 \&\*(Aqhalt\*(Aq is used to signal any harness that no further test files should be run
183 (bail\-out uses this).
184 .Sp
185 \&\*(Aqhas_callback\*(Aq is set to true if the event has a callback sub defined.
186 .Sp
187 \&\*(Aqencoding\*(Aq used to tell the formatter what encoding to use.
188 .ie n .IP "errors => [{details => $string, tag => $short_string, fail => $bool}]" 4
189 .el .IP "errors => [{details => \f(CW$string\fR, tag => \f(CW$short_string\fR, fail => \f(CW$bool\fR}]" 4
190 .IX Item "errors => [{details => $string, tag => $short_string, fail => $bool}]"
191 Documented in Test2::EventFacet::Error. An event may have multiple.
192 .Sp
193 \&\*(Aqdetails\*(Aq is a human readable explanation of the error.
194 .Sp
195 \&\*(Aqtag\*(Aq is a short human readable category for the error.
196 .Sp
197 \&\*(Aqfail\*(Aq is true if the error should cause test failure. If this is false the
198 error is simply informative, but not fatal.
199 .ie n .IP "info => [{details => $string, tag => $short_string, debug => $bool, important => $bool}]" 4
200 .el .IP "info => [{details => \f(CW$string\fR, tag => \f(CW$short_string\fR, debug => \f(CW$bool\fR, important => \f(CW$bool\fR}]" 4
201 .IX Item "info => [{details => $string, tag => $short_string, debug => $bool, important => $bool}]"
202 Documented in Test2::EventFacet::Info. An event may have multiple.
203 .Sp
204 This is how diag and note are implemented.
205 .Sp
206 \&\*(Aqdetails\*(Aq human readable message.
207 .Sp
208 \&\*(Aqtag\*(Aq short category for the message, such as \*(Aqdiag\*(Aq or \*(Aqnote\*(Aq.
209 .Sp
210 \&\*(Aqdebug\*(Aq is true if the message is diagnostics in nature, this is the main
211 difference between a note and a diag.
212 .Sp
213 \&\*(Aqimportant\*(Aq is true if the message is not diagnostics, but is important to have
214 it shown anyway. This is primarily used to communicate with a harness.
215 .ie n .IP "parent => {details => $string, hid => $hid, children => [...], buffered => 1}" 4
216 .el .IP "parent => {details => \f(CW$string\fR, hid => \f(CW$hid\fR, children => [...], buffered => 1}" 4
217 .IX Item "parent => {details => $string, hid => $hid, children => [...], buffered => 1}"
218 Documented in Test2::EventFacet::Parent. An event may have one.
219 .Sp
220 This is used by subtests.
221 .Sp
222 \&\*(Aqdetails\*(Aq human readable name of the subtest.
223 .Sp
224 \&\*(Aqhid\*(Aq subtest hub id.
225 .Sp
226 \&\*(Aqchildren\*(Aq an arrayref containing facet_data instances from all child events.
227 .Sp
228 \&\*(Aqbuffered\*(Aq true if it was a buffered subtest.
229 .ie n .IP "plan => {details => $string, count => $int, skip => $bool, none => $bool}" 4
230 .el .IP "plan => {details => \f(CW$string\fR, count => \f(CW$int\fR, skip => \f(CW$bool\fR, none => \f(CW$bool\fR}" 4
231 .IX Item "plan => {details => $string, count => $int, skip => $bool, none => $bool}"
232 Documented in Test2::EventFacet::Plan. An event may have one.
233 .Sp
234 \&\*(Aqdetails\*(Aq is a human readable string describing the plan (for instance, why a
235 test is skipped)
236 .Sp
237 \&\*(Aqcount\*(Aq is the number of expected assertions (0 for skip)
238 .Sp
239 \&\*(Aqskip\*(Aq is true if the plan is to skip the test.
240 .Sp
241 \&\*(Aqnone\*(Aq used for Test::More\*(Aqs \*(Aqno_plan\*(Aq plan.
242 .ie n .IP "trace => {details => $string, frame => [$pkg, $file, $line, $sub], pid => $int, tid => $int, cid => $cid, hid => $hid, nested => $int, buffered => $bool}" 4
243 .el .IP "trace => {details => \f(CW$string\fR, frame => [$pkg, \f(CW$file\fR, \f(CW$line\fR, \f(CW$sub\fR], pid => \f(CW$int\fR, tid => \f(CW$int\fR, cid => \f(CW$cid\fR, hid => \f(CW$hid\fR, nested => \f(CW$int\fR, buffered => \f(CW$bool\fR}" 4
244 .IX Item "trace => {details => $string, frame => [$pkg, $file, $line, $sub], pid => $int, tid => $int, cid => $cid, hid => $hid, nested => $int, buffered => $bool}"
245 Documented in Test2::EventFacet::Trace. An event may have one.
246 .Sp
247 This is how debugging information is tracked. This is taken from the context
248 object at event creation.
249 .Sp
250 \&\*(Aqdetails\*(Aq human readable debug message (otherwise generated from frame)
251 .Sp
252 \&\*(Aqframe\*(Aq first 4 fields returned by caller:
253 \&\f(CW\*(C`[$package, $file, $line, $subname]\*(C'\fR.
254 .Sp
255 \&\*(Aqpid\*(Aq the process id in which the event was created.
256 .Sp
257 \&\*(Aqtid\*(Aq the thread is in which the event was created.
258 .Sp
259 \&\*(Aqcid\*(Aq the id of the context used to create the event.
260 .Sp
261 \&\*(Aqhid\*(Aq the id of the hub to which the event was sent.
262 .Sp
263 \&\*(Aqnest\*(Aq subtest nesting depth of the event.
264 .Sp
265 \&\*(Aqbuffered\*(Aq is true if the event was generated inside a buffered subtest.
266 .PP
267 Note that ALL facet types have a \*(Aqdetails\*(Aq key that may have a string. This
268 string should always be human readable, and should be an explanation for the
269 facet. For an assertion this is the test name. For a plan this is the reason
270 for the plan (such as skip reason). For info it is the human readable
271 diagnostics message.
272 .SS "CUSTOM FACETS"
273 .IX Subsection "CUSTOM FACETS"
274 You can write custom facet types as well, simply add a new key to the hash and
275 populated it. The general rule is that any code looking at the facets should
276 ignore any it does not understand.
277 .PP
278 Optionally you can also create a package to document your custom facet. The
279 package should be proper object, and may have additional methods to help work
280 with your facet.
281 .PP
282 .Vb 1
283 \& package Test2::EventFacet::MyFacet;
284 \&
285 \& use parent \*(AqTest2::EventFacet\*(Aq;
286 \&
287 \& sub facet_key { \*(Aqmyfacet\*(Aq }
288 \& sub is_list { 0 }
289 \&
290 \& 1;
291 .Ve
292 .PP
293 Your facet package should always be under the Test2::EventFacet:: namespace if
294 you want any tools to automatically find it. The last part of the namespace
295 should be the non\-plural name of your facet with only the first word
296 capitalized.
297 .ie n .IP "$string = $facet_class\->facet_key" 4
298 .el .IP "\f(CW$string\fR = \f(CW$facet_class\fR\->facet_key" 4
299 .IX Item "$string = $facet_class->facet_key"
300 The key for your facet should be the same as the last section of
301 the namespace, but all lowercase. You \fImay\fR append \*(Aqs\*(Aq to the key if your
302 facet is a list type.
303 .ie n .IP "$bool = $facet_class\->is_list" 4
304 .el .IP "\f(CW$bool\fR = \f(CW$facet_class\fR\->is_list" 4
305 .IX Item "$bool = $facet_class->is_list"
306 True if an event should put these facets in a list:
307 .Sp
308 .Vb 1
309 \& { myfacet => [{}, {}] }
310 .Ve
311 .Sp
312 False if an event may only have one of this type of facet at a time:
313 .Sp
314 .Vb 1
315 \& { myfacet => {} }
316 .Ve
317 .PP
318 \fIEXAMPLES\fR
319 .IX Subsection "EXAMPLES"
320 .PP
321 The assert facet is not a list type, so its implementation would look like this:
322 .PP
323 .Vb 3
324 \& package Test2::EventFacet::Assert;
325 \& sub facet_key { \*(Aqassert\*(Aq }
326 \& sub is_list { 0 }
327 .Ve
328 .PP
329 The amnesty facet is a list type, but amnesty does not need \*(Aqs\*(Aq appended to
330 make it plural:
331 .PP
332 .Vb 3
333 \& package Test2::EventFacet::Amnesty;
334 \& sub facet_key { \*(Aqamnesty\*(Aq }
335 \& sub is_list { 1 }
336 .Ve
337 .PP
338 The error facet is a list type, and appending \*(Aqs\*(Aq makes error plural as errors.
339 This means the package name is \*(Aq::Error\*(Aq, but the key is \*(Aqerrors\*(Aq.
340 .PP
341 .Vb 3
342 \& package Test2::EventFacet::Error;
343 \& sub facet_key { \*(Aqerrors\*(Aq }
344 \& sub is_list { 1 }
345 .Ve
346 .PP
347 \&\fBNote2:\fR In practice most tools completely ignore the facet packages, and work
348 with the facet data directly in its raw structure. This is by design and
349 recommended. The facet data is intended to be serialized frequently and passed
350 around. When facets are concerned, data is important, classes and methods are
351 not.
352 .SH "THE OLD API"
353 .IX Header "THE OLD API"
354 The old API was simply a set of methods you were required to implement:
355 .ie n .IP "$bool = $e\->causes_fail" 4
356 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->causes_fail" 4
357 .IX Item "$bool = $e->causes_fail"
358 Returns true if this event should result in a test failure. In general this
359 should be false.
360 .ie n .IP "$bool = $e\->increments_count" 4
361 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->increments_count" 4
362 .IX Item "$bool = $e->increments_count"
363 Should be true if this event should result in a test count increment.
364 .ie n .IP $e\->callback($hub) 4
365 .el .IP \f(CW$e\fR\->callback($hub) 4
366 .IX Item "$e->callback($hub)"
367 If your event needs to have extra effects on the Test2::Hub you can override
368 this method.
369 .Sp
370 This is called \fBBEFORE\fR your event is passed to the formatter.
371 .ie n .IP "$num = $e\->nested" 4
372 .el .IP "\f(CW$num\fR = \f(CW$e\fR\->nested" 4
373 .IX Item "$num = $e->nested"
374 If this event is nested inside of other events, this should be the depth of
375 nesting. (This is mainly for subtests)
376 .ie n .IP "$bool = $e\->global" 4
377 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->global" 4
378 .IX Item "$bool = $e->global"
379 Set this to true if your event is global, that is ALL threads and processes
380 should see it no matter when or where it is generated. This is not a common
381 thing to want, it is used by bail\-out and skip_all to end testing.
382 .ie n .IP "$code = $e\->terminate" 4
383 .el .IP "\f(CW$code\fR = \f(CW$e\fR\->terminate" 4
384 .IX Item "$code = $e->terminate"
385 This is called \fBAFTER\fR your event has been passed to the formatter. This
386 should normally return undef, only change this if your event should cause the
387 test to exit immediately.
388 .Sp
389 If you want this event to cause the test to exit you should return the exit
390 code here. Exit code of 0 means exit success, any other integer means exit with
391 failure.
392 .Sp
393 This is used by Test2::Event::Plan to exit 0 when the plan is
394 \&\*(Aqskip_all\*(Aq. This is also used by Test2::Event:Bail to force the test
395 to exit with a failure.
396 .Sp
397 This is called after the event has been sent to the formatter in order to
398 ensure the event is seen and understood.
399 .ie n .IP "$msg = $e\->summary" 4
400 .el .IP "\f(CW$msg\fR = \f(CW$e\fR\->summary" 4
401 .IX Item "$msg = $e->summary"
402 This is intended to be a human readable summary of the event. This should
403 ideally only be one line long, but you can use multiple lines if necessary. This
404 is intended for human consumption. You do not need to make it easy for machines
405 to understand.
406 .Sp
407 The default is to simply return the event package name.
408 .ie n .IP "($count, $directive, $reason) = $e\->\fBsets_plan()\fR" 4
409 .el .IP "($count, \f(CW$directive\fR, \f(CW$reason\fR) = \f(CW$e\fR\->\fBsets_plan()\fR" 4
410 .IX Item "($count, $directive, $reason) = $e->sets_plan()"
411 Check if this event sets the testing plan. It will return an empty list if it
412 does not. If it does set the plan it will return a list of 1 to 3 items in
413 order: Expected Test Count, Test Directive, Reason for directive.
414 .ie n .IP "$bool = $e\->diagnostics" 4
415 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->diagnostics" 4
416 .IX Item "$bool = $e->diagnostics"
417 True if the event contains diagnostics info. This is useful because a
418 non\-verbose harness may choose to hide events that are not in this category.
419 Some formatters may choose to send these to STDERR instead of STDOUT to ensure
420 they are seen.
421 .ie n .IP "$bool = $e\->no_display" 4
422 .el .IP "\f(CW$bool\fR = \f(CW$e\fR\->no_display" 4
423 .IX Item "$bool = $e->no_display"
424 False by default. This will return true on events that should not be displayed
425 by formatters.
426 .SH "SEE ALSO"
427 .IX Header "SEE ALSO"
428 Test2::Manual \- Primary index of the manual.
429 .SH SOURCE
430 .IX Header "SOURCE"
431 The source code repository for Test2\-Manual can be found at
432 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
433 .SH MAINTAINERS
434 .IX Header "MAINTAINERS"
435 .IP "Chad Granum <[email protected]>" 4
436 .IX Item "Chad Granum <[email protected]>"
437 .SH AUTHORS
438 .IX Header "AUTHORS"
439 .IP "Chad Granum <[email protected]>" 4
440 .IX Item "Chad Granum <[email protected]>"
441 .SH COPYRIGHT
442 .IX Header "COPYRIGHT"
443 Copyright Chad Granum <[email protected]>.
444 .PP
445 This program is free software; you can redistribute it and/or
446 modify it under the same terms as Perl itself.
447 .PP
448 See \fIhttp://dev.perl.org/licenses/\fR