1Test2::Manual::Anatomy:U:sEevrenCto(n3t)ributed Perl DocTuemsetn2t:a:tMiaonnual::Anatomy::Event(3)
2
3
4

NAME

6       Test2::Manual::Anatomy::Event - The internals of events
7

DESCRIPTION

9       Events are how tools effect global state, and pass information along to
10       the harness, or the human running the tests.
11

HISTORY

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
19       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

THE EVENT OBJECT

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
31       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
35       Here is a good template for a new event:
36
37           package Test2::Event::Mine;
38           use strict;
39           use warnings;
40
41           use parent 'Test2::Event';
42           use Test2::Util::Facets2Legacy ':ALL';
43
44           sub facet_data {
45               my $self = shift;
46
47               # Adds 'about', 'amnesty', and 'trace' facets
48               my $out = $self->common_facet_data;
49
50               # Add any additional facets to the $out hashref
51               ...
52
53               return $out;
54           }
55
56           1;
57

THE FACET API

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
64       The standard facet types are as follows:
65
66       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
71           The 'details' key is the name of the assertion.
72
73           The 'pass' key denotes a passing or failing assertion.
74
75           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
79           The 'number' key is for harness use, never set it yourself.
80
81       about => {details => $string, no_display => $bool, package => $pkg}
82           Documented in Test2::EventFacet::About. An event may only have one.
83
84           'details' is a human readable string describing the overall event.
85
86           'no_display' means that a formatter/harness should hide the event.
87
88           'package' is the package of the event the facet describes (IE:
89           Test2::Event::Ok)
90
91       amnesty => [{details => $string, tag => $short_string, inherited =>
92       $bool}]
93           Documented in Test2::EventFacet::Amnesty. An event may have
94           multiple.
95
96           This event is how things like 'todo' are implemented. Amnesty
97           prevents a failing assertion from causing a global test failure.
98
99           'details' is a human readable description of why the failure is
100           being granted amnesty (IE The 'todo' reason)
101
102           'tag' is a short human readable string, or category for the
103           amnesty. This is typically 'TODO' or 'SKIP'.
104
105           '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
108       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
112           This facet is used to apply extra behavior when the event is
113           processed.
114
115           'details' is a human readable explanation for the behavior.
116
117           'global' true if this event should be forwarded to, and processed
118           by, all hubs everywhere. (bail-out uses this)
119
120           '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
124           'halt' is used to signal any harness that no further test files
125           should be run (bail-out uses this).
126
127           'has_callback' is set to true if the event has a callback sub
128           defined.
129
130           'encoding' used to tell the formatter what encoding to use.
131
132       errors => [{details => $string, tag => $short_string, fail => $bool}]
133           Documented in Test2::EventFacet::Error. An event may have multiple.
134
135           'details' is a human readable explanation of the error.
136
137           'tag' is a short human readable category for the error.
138
139           'fail' is true if the error should cause test failure. If this is
140           false the error is simply informative, but not fatal.
141
142       info => [{details => $string, tag => $short_string, debug => $bool,
143       important => $bool}]
144           Documented in Test2::EventFacet::Info. An event may have multiple.
145
146           This is how diag and note are implemented.
147
148           'details' human readable message.
149
150           'tag' short category for the message, such as 'diag' or 'note'.
151
152           'debug' is true if the message is diagnostics in nature, this is
153           the main difference between a note and a diag.
154
155           '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
159       parent => {details => $string, hid => $hid, children => [...], buffered
160       => 1}
161           Documented in Test2::EventFacet::Parent. An event may have one.
162
163           This is used by subtests.
164
165           'details' human readable name of the subtest.
166
167           'hid' subtest hub id.
168
169           'children' an arrayref containing facet_data instances from all
170           child events.
171
172           'buffered' true if it was a buffered subtest.
173
174       plan => {details => $string, count => $int, skip => $bool, none =>
175       $bool}
176           Documented in Test2::EventFacet::Plan. An event may have one.
177
178           'details' is a human readable string describing the plan (for
179           instance, why a test is skipped)
180
181           'count' is the number of expected assertions (0 for skip)
182
183           'skip' is true if the plan is to skip the test.
184
185           'none' used for Test::More's 'no_plan' plan.
186
187       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
192           This is how debugging information is tracked. This is taken from
193           the context object at event creation.
194
195           'details' human readable debug message (otherwise generated from
196           frame)
197
198           'frame' first 4 fields returned by caller: "[$package, $file,
199           $line, $subname]".
200
201           'pid' the process id in which the event was created.
202
203           'tid' the thread is in which the event was created.
204
205           'cid' the id of the context used to create the event.
206
207           'hid' the id of the hub to which the event was sent.
208
209           'nest' subtest nesting depth of the event.
210
211           'buffered' is true if the event was generated inside a buffered
212           subtest.
213
214       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
220   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
225       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
229           package Test2::EventFacet::MyFacet;
230
231           use parent 'Test2::EventFacet';
232
233           sub facet_key { 'myfacet' }
234           sub is_list { 0 }
235
236           1;
237
238       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
243       $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
248       $bool = $facet_class->is_list
249           True if an event should put these facets in a list:
250
251               { myfacet => [{}, {}] }
252
253           False if an event may only have one of this type of facet at a
254           time:
255
256               { myfacet => {} }
257
258       EXAMPLES
259
260       The assert facet is not a list type, so its implementation would look
261       like this:
262
263           package Test2::EventFacet::Assert;
264           sub facet_key { 'assert' }
265           sub is_list { 0 }
266
267       The amnesty facet is a list type, but amnesty does not need 's'
268       appended to make it plural:
269
270           package Test2::EventFacet::Amnesty;
271           sub facet_key { 'amnesty' }
272           sub is_list { 1 }
273
274       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
278           package Test2::EventFacet::Error;
279           sub facet_key { 'errors' }
280           sub is_list { 1 }
281
282       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
288       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

THE OLD API

295       The old API was simply a set of methods you were required to implement:
296
297       $bool = $e->causes_fail
298           Returns true if this event should result in a test failure. In
299           general this should be false.
300
301       $bool = $e->increments_count
302           Should be true if this event should result in a test count
303           increment.
304
305       $e->callback($hub)
306           If your event needs to have extra effects on the Test2::Hub you can
307           override this method.
308
309           This is called BEFORE your event is passed to the formatter.
310
311       $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
315       $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
321       $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
326           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
330           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
334           This is called after the event has been sent to the formatter in
335           order to ensure the event is seen and understood.
336
337       $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
343           The default is to simply return the event package name.
344
345       ($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
351       $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
357       $bool = $e->no_display
358           False by default. This will return true on events that should not
359           be displayed by formatters.
360

SEE ALSO

362       Test2::Manual - Primary index of the manual.
363

SOURCE

365       The source code repository for Test2-Manual can be found at
366       https://github.com/Test-More/Test2-Suite/.
367

MAINTAINERS

369       Chad Granum <exodist@cpan.org>
370

AUTHORS

372       Chad Granum <exodist@cpan.org>
373
375       Copyright 2018 Chad Granum <exodist@cpan.org>.
376
377       This program is free software; you can redistribute it and/or modify it
378       under the same terms as Perl itself.
379
380       See http://dev.perl.org/licenses/
381
382
383
384perl v5.36.0                      2022-07-22  Test2::Manual::Anatomy::Event(3)
Impressum