1Test2::Manual::Anatomy:U:sEevrenCto(n3t)ributed Perl DocTuemsetn2t:a:tMiaonnual::Anatomy::Event(3)
2
6 Test2::Manual::Anatomy::Event - The internals of events
7
9 Events are how tools effect global state, and pass information along to
10 the harness, or the human running the tests.
11
13 Before proceeding it is important that you know some history of events.
14 Initially there was an event API, and an event would implement the API
15 to produce an effect. This API proved to be lossy and inflexible.
16 Recently the 'facet' system was introduced, and makes up for the
17 shortcoming and inflexibility of the old API.
18 All events must still implement the old API, but that can be largely
20 automated if you use the facet system effectively. Likewise essential
21 facets can often be deduced from events that only implement the old
22 API, though their information maybe less complete.
23
25 All event objects must subclass Test2::Event. If you inherit from this
26 base class, and implement the old API properly, facets will be
27 generated for you for free. On the other hand you can inherit from
28 this, and also import Test2::Util::Facets2Legacy which will instead
29 rely on your facet data, and deduce the old API from them.
30 All new events "MUST" implement both APIs one way or the other. A
32 common way to do this is to simply implement both APIs directly in your
33 event.
34 Here is a good template for a new event:
36 package Test2::Event::Mine;
38 use strict;
39 use warnings;
40 use parent 'Test2::Event';
42 use Test2::Util::Facets2Legacy ':ALL';
43 sub facet_data {
45 my $self = shift;
46 # Adds 'about', 'amnesty', and 'trace' facets
48 my $out = $self->common_facet_data;
49 # Add any additional facets to the $out hashref
51 ...
52 return $out;
54 }
55 1;
57
59 The new API is a single method: "facet_data()". This method must return
60 a hashref where each key is specific to a facet type, and the value is
61 either a facet hashref, or an array of hashrefs. Some facets "MUST" be
62 lone hashrefs, others "MUST" be hashrefs inside an arrayref.
63 The standard facet types are as follows:
65 assert => {details => $name, pass => $bool, no_debug => $bool, number
67 => $maybe_int}
68 Documented in Test2::EventFacet::Assert. An event may only have
69 one.
70 The 'details' key is the name of the assertion.
72 The 'pass' key denotes a passing or failing assertion.
74 The 'no_debug' key tells any harness or formatter that diagnostics
76 should not be added automatically to a failing assertion (used when
77 there are custom diagnostics instead).
78 The 'number' key is for harness use, never set it yourself.
80 about => {details => $string, no_display => $bool, package => $pkg}
82 Documented in Test2::EventFacet::About. An event may only have one.
83 'details' is a human readable string describing the overall event.
85 'no_display' means that a formatter/harness should hide the event.
87 'package' is the package of the event the facet describes (IE:
89 Test2::Event::Ok)
90 amnesty => [{details => $string, tag => $short_string, inherited =>
92 $bool}]
93 Documented in Test2::EventFacet::Amnesty. An event may have
94 multiple.
95 This event is how things like 'todo' are implemented. Amnesty
97 prevents a failing assertion from causing a global test failure.
98 'details' is a human readable description of why the failure is
100 being granted amnesty (IE The 'todo' reason)
101 'tag' is a short human readable string, or category for the
103 amnesty. This is typically 'TODO' or 'SKIP'.
104 'inherited' is true if the amnesty was applied in a parent context
106 (true if this test is run in a subtest that is marked todo).
107 control => {details => $string, global => $bool, terminate =>
109 $maybe_int, halt => $bool, has_callback => $bool, encoding => $enc}
110 Documented in Test2::EventFacet::Control. An event may have one.
111 This facet is used to apply extra behavior when the event is
113 processed.
114 'details' is a human readable explanation for the behavior.
116 'global' true if this event should be forwarded to, and processed
118 by, all hubs everywhere. (bail-out uses this)
119 'terminate' this should either be undef, or an integer. When
121 defined this will cause the test to exit with the specific exit
122 code.
123 'halt' is used to signal any harness that no further test files
125 should be run (bail-out uses this).
126 'has_callback' is set to true if the event has a callback sub
128 defined.
129 'encoding' used to tell the formatter what encoding to use.
131 errors => [{details => $string, tag => $short_string, fail => $bool}]
133 Documented in Test2::EventFacet::Error. An event may have multiple.
134 'details' is a human readable explanation of the error.
136 'tag' is a short human readable category for the error.
138 'fail' is true if the error should cause test failure. If this is
140 false the error is simply informative, but not fatal.
141 info => [{details => $string, tag => $short_string, debug => $bool,
143 important => $bool}]
144 Documented in Test2::EventFacet::Info. An event may have multiple.
145 This is how diag and note are implemented.
147 'details' human readable message.
149 'tag' short category for the message, such as 'diag' or 'note'.
151 'debug' is true if the message is diagnostics in nature, this is
153 the main difference between a note and a diag.
154 'important' is true if the message is not diagnostics, but is
156 important to have it shown anyway. This is primarily used to
157 communicate with a harness.
158 parent => {details => $string, hid => $hid, children => [...], buffered
160 => 1}
161 Documented in Test2::EventFacet::Parent. An event may have one.
162 This is used by subtests.
164 'details' human readable name of the subtest.
166 'hid' subtest hub id.
168 'children' an arrayref containing facet_data instances from all
170 child events.
171 'buffered' true if it was a buffered subtest.
173 plan => {details => $string, count => $int, skip => $bool, none =>
175 $bool}
176 Documented in Test2::EventFacet::Plan. An event may have one.
177 'details' is a human readable string describing the plan (for
179 instance, why a test is skipped)
180 'count' is the number of expected assertions (0 for skip)
182 'skip' is true if the plan is to skip the test.
184 'none' used for Test::More's 'no_plan' plan.
186 trace => {details => $string, frame => [$pkg, $file, $line, $sub], pid
188 => $int, tid => $int, cid => $cid, hid => $hid, nested => $int,
189 buffered => $bool}
190 Documented in Test2::EventFacet::Trace. An event may have one.
191 This is how debugging information is tracked. This is taken from
193 the context object at event creation.
194 'details' human readable debug message (otherwise generated from
196 frame)
197 'frame' first 4 fields returned by caller: "[$package, $file,
199 $line, $subname]".
200 'pid' the process id in which the event was created.
202 'tid' the thread is in which the event was created.
204 'cid' the id of the context used to create the event.
206 'hid' the id of the hub to which the event was sent.
208 'nest' subtest nesting depth of the event.
210 'buffered' is true if the event was generated inside a buffered
212 subtest.
213 Note that ALL facet types have a 'details' key that may have a string.
215 This string should always be human readable, and should be an
216 explanation for the facet. For an assertion this is the test name. For
217 a plan this is the reason for the plan (such as skip reason). For info
218 it is the human readable diagnostics message.
219 CUSTOM FACETS
221 You can write custom facet types as well, simply add a new key to the
222 hash and populated it. The general rule is that any code looking at the
223 facets should ignore any it does not understand.
224 Optionally you can also create a package to document your custom facet.
226 The package should be proper object, and may have additional methods to
227 help work with your facet.
228 package Test2::EventFacet::MyFacet;
230 use parent 'Test2::EventFacet';
232 sub facet_key { 'myfacet' }
234 sub is_list { 0 }
235 1;
237 Your facet package should always be under the Test2::EventFacet::
239 namespace if you want any tools to automatically find it. The last part
240 of the namespace should be the non-plural name of your facet with only
241 the first word capitalized.
242 $string = $facet_class->facet_key
244 The key for your facet should be the same as the last section of
245 the namespace, but all lowercase. You may append 's' to the key if
246 your facet is a list type.
247 $bool = $facet_class->is_list
249 True if an event should put these facets in a list:
250 { myfacet => [{}, {}] }
252 False if an event may only have one of this type of facet at a
254 time:
255 { myfacet => {} }
257 EXAMPLES
259 The assert facet is not a list type, so its implementation would look
261 like this:
262 package Test2::EventFacet::Assert;
264 sub facet_key { 'assert' }
265 sub is_list { 0 }
266 The amnesty facet is a list type, but amnesty does not need 's'
268 appended to make it plural:
269 package Test2::EventFacet::Amnesty;
271 sub facet_key { 'amnesty' }
272 sub is_list { 1 }
273 The error facet is a list type, and appending 's' makes error plural as
275 errors. This means the package name is '::Error', but the key is
276 'errors'.
277 package Test2::EventFacet::Error;
279 sub facet_key { 'errors' }
280 sub is_list { 1 }
281 Note Do not worry too much about getting the key/pluralization wrong.
283 Most tools will use Module::Pluggable to load all facet types and build
284 a hash linking keys to packages and so on, working backwards. This
285 means, in general, that even if you get it wrong any tool that NEEDS
286 the package for the facet will find it.
287 Note2: In practice most tools completely ignore the facet packages, and
289 work with the facet data directly in its raw structure. This is by
290 design and recommended. The facet data is intended to be serialized
291 frequently and passed around. When facets are concerned, data is
292 important, classes and methods are not.
293
295 The old API was simply a set of methods you were required to implement:
296 $bool = $e->causes_fail
298 Returns true if this event should result in a test failure. In
299 general this should be false.
300 $bool = $e->increments_count
302 Should be true if this event should result in a test count
303 increment.
304 $e->callback($hub)
306 If your event needs to have extra effects on the Test2::Hub you can
307 override this method.
308 This is called BEFORE your event is passed to the formatter.
310 $num = $e->nested
312 If this event is nested inside of other events, this should be the
313 depth of nesting. (This is mainly for subtests)
314 $bool = $e->global
316 Set this to true if your event is global, that is ALL threads and
317 processes should see it no matter when or where it is generated.
318 This is not a common thing to want, it is used by bail-out and
319 skip_all to end testing.
320 $code = $e->terminate
322 This is called AFTER your event has been passed to the formatter.
323 This should normally return undef, only change this if your event
324 should cause the test to exit immediately.
325 If you want this event to cause the test to exit you should return
327 the exit code here. Exit code of 0 means exit success, any other
328 integer means exit with failure.
329 This is used by Test2::Event::Plan to exit 0 when the plan is
331 'skip_all'. This is also used by Test2::Event:Bail to force the
332 test to exit with a failure.
333 This is called after the event has been sent to the formatter in
335 order to ensure the event is seen and understood.
336 $msg = $e->summary
338 This is intended to be a human readable summary of the event. This
339 should ideally only be one line long, but you can use multiple
340 lines if necessary. This is intended for human consumption. You do
341 not need to make it easy for machines to understand.
342 The default is to simply return the event package name.
344 ($count, $directive, $reason) = $e->sets_plan()
346 Check if this event sets the testing plan. It will return an empty
347 list if it does not. If it does set the plan it will return a list
348 of 1 to 3 items in order: Expected Test Count, Test Directive,
349 Reason for directive.
350 $bool = $e->diagnostics
352 True if the event contains diagnostics info. This is useful because
353 a non-verbose harness may choose to hide events that are not in
354 this category. Some formatters may choose to send these to STDERR
355 instead of STDOUT to ensure they are seen.
356 $bool = $e->no_display
358 False by default. This will return true on events that should not
359 be displayed by formatters.
360
362 Test2::Manual - Primary index of the manual.
363
365 The source code repository for Test2-Manual can be found at
366 https://github.com/Test-More/Test2-Suite/.
367
369 Chad Granum <exodist@cpan.org>
370
372 Chad Granum <exodist@cpan.org>
373
375 Copyright 2018 Chad Granum <exodist@cpan.org>.
376 This program is free software; you can redistribute it and/or modify it
378 under the same terms as Perl itself.
379 See http://dev.perl.org/licenses/
381perl v5.36.0 2022-07-22 Test2::Manual::Anatomy::Event(3)