5 our $VERSION = '1.302103';
7 use Test2::Util::HashBase qw/trace -amnesty/;
8 use Test2::Util::ExternalMeta qw/meta get_meta set_meta delete_meta/;
9 use Test2::Util qw(pkg_to_file);
11 use Test2::EventFacet::About();
12 use Test2::EventFacet::Amnesty();
13 use Test2::EventFacet::Assert();
14 use Test2::EventFacet::Control();
15 use Test2::EventFacet::Error();
16 use Test2::EventFacet::Info();
17 use Test2::EventFacet::Meta();
18 use Test2::EventFacet::Parent();
19 use Test2::EventFacet::Plan();
20 use Test2::EventFacet::Trace();
23 Test2::EventFacet::About
24 Test2::EventFacet::Amnesty
25 Test2::EventFacet::Assert
26 Test2::EventFacet::Control
27 Test2::EventFacet::Error
28 Test2::EventFacet::Info
29 Test2::EventFacet::Meta
30 Test2::EventFacet::Parent
31 Test2::EventFacet::Plan
32 Test2::EventFacet::Trace
35 sub FACET_TYPES() { @FACET_TYPES }
37 # Legacy tools will expect this to be loaded now
38 require Test2::Util::Trace;
42 sub increments_count { 0 }
45 sub subtest_id { undef }
53 sub summary { ref($_[0]) }
59 my $tracea = $self->trace or return undef;
60 my $traceb = $event->trace or return undef;
62 my $siga = $tracea->signature or return undef;
63 my $sigb = $traceb->signature or return undef;
65 return 1 if $siga eq $sigb;
73 $am = {%$am} if ref($am) ne 'ARRAY';
74 $am = Test2::EventFacet::Amnesty->new($am);
76 push @{$self->{+AMNESTY}} => $am;
80 sub common_facet_data {
85 $out{about} = {package => ref($self) || undef};
87 if (my $trace = $self->trace) {
88 $out{trace} = { %$trace };
91 $out{amnesty} = [map {{ %{$_} }} @{$self->{+AMNESTY}}]
94 my $key = Test2::Util::ExternalMeta::META_KEY();
95 if (my $hash = $self->{$key}) {
96 $out{meta} = {%$hash};
105 my $out = $self->common_facet_data;
107 $out->{about}->{details} = $self->summary || undef;
108 $out->{about}->{no_display} = $self->no_display || undef;
110 # Might be undef, we want to preserve that
111 my $terminate = $self->terminate;
113 global => $self->global || 0,
114 terminate => $terminate,
115 has_callback => $self->can('callback') == \&callback ? 0 : 1,
119 no_debug => 1, # Legacy behavior
120 pass => $self->causes_fail ? 0 : 1,
121 details => $self->summary,
122 } if $self->increments_count;
124 $out->{parent} = {hid => $self->subtest_id} if $self->subtest_id;
126 if (my @plan = $self->sets_plan) {
129 $out->{plan}->{count} = $plan[0] if defined $plan[0];
130 $out->{plan}->{details} = $plan[2] if defined $plan[2];
133 $out->{plan}->{skip} = 1 if $plan[1] eq 'SKIP';
134 $out->{plan}->{none} = 1 if $plan[1] eq 'NO PLAN';
137 $out->{control}->{terminate} ||= 0 if $out->{plan}->{skip};
140 if ($self->causes_fail && !$out->{assert}) {
145 details => $self->summary,
150 my %IGNORE = (trace => 1, about => 1, control => 1);
151 my $do_info = !grep { !$IGNORE{$_} } keys %$out;
153 if ($do_info && !$self->no_display && $self->diagnostics) {
158 details => $self->summary,
168 my $data = $self->facet_data;
171 for my $type (FACET_TYPES()) {
172 my $key = $type->facet_key;
173 next unless $data->{$key};
175 if ($type->is_list) {
176 $out{$key} = [map { $type->new($_) } @{$data->{$key}}];
179 $out{$key} = $type->new($data->{$key});
187 Carp::cluck("Use of Test2::Event->nested() is deprecated, use Test2::Event->trace->nested instead")
188 if $ENV{AUTHOR_TESTING};
190 $_[0]->{+TRACE}->{nested};
194 Carp::cluck("Use of Test2::Event->in_subtest() is deprecated, use Test2::Event->trace->hid instead")
195 if $ENV{AUTHOR_TESTING};
197 # Return undef if we are not nested, Legacy did not return the hid if nestign was 0.
198 return undef unless $_[0]->{+TRACE}->{nested};
200 $_[0]->{+TRACE}->{hid};
213 Test2::Event - Base class for events
217 Base class for all event objects that get passed through
222 package Test2::Event::MyEvent;
226 # This will make our class an event subclass (required)
227 use base 'Test2::Event';
229 # Add some accessors (optional)
230 # You are not obligated to use HashBase, you can use any object tool you
231 # want, or roll your own accessors.
232 use Test2::Util::HashBase qw/foo bar baz/;
234 # Use this if you want the legacy API to be written for you, for this to
235 # work you will need to implement a facet_data() method.
236 use Test2::Util::Facets2Legacy;
238 # Chance to initialize some defaults
241 # no other args in @_
243 $self->set_foo('xxx') unless defined $self->foo;
248 # This is the new way for events to convey data to the Test2 system
252 # Get common facets such as 'about', 'trace' 'amnesty', and 'meta'
253 my $facet_data = $self->common_facet_data();
255 # Are you making an assertion?
256 $facet_data->{assert} = {pass => 1, details => 'my assertion'};
270 =item $trace = $e->trace
272 Get a snapshot of the L<Test2::EventFacet::Trace> as it was when this event was
275 =item $bool_or_undef = $e->related($e2)
277 Check if 2 events are related. In this case related means their traces share a
278 signature meaning they were created with the same context (or at the very least
279 by contexts which share an id, which is the same thing unless someone is doing
282 This can be used to reliably link multiple events created by the same tool. For
283 instance a failing test like C<ok(0, "fail"> will generate 2 events, one being
284 a L<Test2::Event::Ok>, the other being a L<Test2::Event::Diag>, both of these
285 events are related having been created under the same context and by the same
286 initial tool (though multiple tools may have been nested under the initial
289 This will return C<undef> if the relationship cannot be checked, which happens
290 if either event has an incomplete or missing trace. This will return C<0> if
291 the traces are complete, but do not match. C<1> will be returned if there is a
294 =item $e->add_amnesty({tag => $TAG, details => $DETAILS});
296 This can be used to add amnesty to this event. Amnesty only effects failing
297 assertions in most cases, but some formatters may display them for passing
298 assertions, or even non-assertions as well.
300 Amnesty will prevent a failed assertion from causing the overall test to fail.
301 In other words it marks a failure as expected and allowed.
303 B<Note:> This is how 'TODO' is implemented under the hood. TODO is essentially
304 amnesty with the 'TODO' tag. The details are the reason for the TODO.
312 =item $hashref = $e->common_facet_data();
314 This can be used by subclasses to generate a starting facet data hashref. This
315 will populate the hashref with the trace, meta, amnesty, and about facets.
316 These facets are nearly always produced the same way for all events.
318 =item $hashref = $e->facet_data()
320 If you do not override this then the default implementation will attempt to
321 generate facets from the legacy API. This generation is limited only to what
322 the legacy API can provide. It is recommended that you override this method and
323 write out explicit facet data.
325 =item $hashref = $e->facets()
327 This takes the hashref from C<facet_data()> and blesses each facet into the
328 proper C<Test2::EventFacet::*> subclass.
332 =head3 WHAT ARE FACETS?
334 Facets are how events convey their purpose to the Test2 internals and
335 formatters. An event without facets will have no intentional effect on the
336 overall test state, and will not be displayed at all by most formatters, except
337 perhaps to say that an event of an unknown type was seen.
339 Facets are produced by the C<facet_data()> subroutine, which you should
340 nearly-always override. C<facet_data()> is expected to return a hashref where
341 each key is the facet type, and the value is either a hashref with the data for
342 that facet, or an array of hashref's. Some facets must be defined as single
343 hashrefs, some must be defined as an array of hashrefs, No facets allow both.
345 C<facet_data()> B<MUST NOT> bless the data it returns, the main hashref, and
346 nested facet hashref's B<MUST> be bare, though items contained within each
347 facet may be blessed. The data returned by this method B<should> also be copies
348 of the internal data in order to prevent accidental state modification.
350 C<facets()> takes the data from C<facet_data()> and blesses it into the
351 C<Test2::EventFacet::*> packages. This is rarely used however, the EventFacet
352 packages are primarily for convenience and documentation. The EventFacet
353 classes are not used at all internally, instead the raw data is used.
355 Here is a list of facet types by package. The packages are not used internally,
356 but are where the documentation for each type is kept.
358 B<Note:> Every single facet type has the C<'details'> field. This field is
359 always intended for human consumption, and when provided, should explain the
360 'why' for the facet. All other fields are facet specific.
366 L<Test2::EventFacet::About>
368 This contains information about the event itself such as the event package
369 name. The C<details> field for this facet is an overall summary of the event.
371 =item assert => {...}
373 L<Test2::EventFacet::Assert>
375 This facet is used if an assertion was made. The C<details> field of this facet
376 is the description of the assertion.
378 =item control => {...}
380 L<Test2::EventFacet::Control>
382 This facet is used to tell the L<Test2::Event::Hub> about special actions the
383 event causes. Things like halting all testing, terminating the current test,
384 etc. In this facet the C<details> field explains why any special action was
387 B<Note:> This is how bail-out is implemented.
391 L<Test2::EventFacet::Meta>
393 The meta facet contains all the meta-data attached to the event. In this case
394 the C<details> field has no special meaning, but may be present if something
395 sets the 'details' meta-key on the event.
397 =item parent => {...}
399 L<Test2::EventFacet::Parent>
401 This facet contains nested events and similar details for subtests. In this
402 facet the C<details> field will typically be the name of the subtest.
406 L<Test2::EventFacet::Plan>
408 This facet tells the system that a plan has been set. The C<details> field of
409 this is usually left empty, but when present explains why the plan is what it
410 is, this is most useful if the plan is to skip-all.
414 L<Test2::EventFacet::Trace>
416 This facet contains information related to when and where the event was
417 generated. This is how the test file and line number of a failure is known.
418 This facet can also help you to tell if tests are related.
420 In this facet the C<details> field overrides the "failed at test_file.t line
421 42." message provided on assertion failure.
423 =item amnesty => [{...}, ...]
425 L<Test2::EventFacet::Amnesty>
427 The amnesty facet is a list instead of a single item, this is important as
428 amnesty can come from multiple places at once.
430 For each instance of amnesty the C<details> field explains why amnesty was
433 B<Note:> Outside of formatters amnesty only acts to forgive a failing
436 =item errors => [{...}, ...]
438 L<Test2::EventFacet::Error>
440 The errors facet is a list instead of a single item, any number of errors can
441 be listed. In this facet C<details> describes the error, or may contain the raw
442 error message itself (such as an exception). In perl exception may be blessed
443 objects, as such the raw data for this facet may contain nested items which are
446 Not all errors are considered fatal, there is a C<fail> field that must be set
447 for an error to cause the test to fail.
449 B<Note:> This facet is unique in that the field name is 'errors' while the
450 package is 'Error'. This is because this is the only facet type that is both a
451 list, and has a name where the plural is not the same as the singular. This may
452 cause some confusion, but I feel it will be less confusing than the
455 =item info => [{...}, ...]
457 L<Test2::EventFacet::Info>
459 The 'info' facet is a list instead of a single item, any quantity of extra
460 information can be attached to an event. Some information may be critical
461 diagnostics, others may be simply commentary in nature, this is determined by
464 For this facet the C<details> flag is the info itself. This info may be a
465 string, or it may be a data structure to display. This is one of the few facet
466 types that may contain blessed items.
474 =item $bool = $e->causes_fail
476 Returns true if this event should result in a test failure. In general this
479 =item $bool = $e->increments_count
481 Should be true if this event should result in a test count increment.
483 =item $e->callback($hub)
485 If your event needs to have extra effects on the L<Test2::Hub> you can override
488 This is called B<BEFORE> your event is passed to the formatter.
490 =item $num = $e->nested
492 If this event is nested inside of other events, this should be the depth of
493 nesting. (This is mainly for subtests)
495 =item $bool = $e->global
497 Set this to true if your event is global, that is ALL threads and processes
498 should see it no matter when or where it is generated. This is not a common
499 thing to want, it is used by bail-out and skip_all to end testing.
501 =item $code = $e->terminate
503 This is called B<AFTER> your event has been passed to the formatter. This
504 should normally return undef, only change this if your event should cause the
505 test to exit immediately.
507 If you want this event to cause the test to exit you should return the exit
508 code here. Exit code of 0 means exit success, any other integer means exit with
511 This is used by L<Test2::Event::Plan> to exit 0 when the plan is
512 'skip_all'. This is also used by L<Test2::Event:Bail> to force the test
513 to exit with a failure.
515 This is called after the event has been sent to the formatter in order to
516 ensure the event is seen and understood.
518 =item $msg = $e->summary
520 This is intended to be a human readable summary of the event. This should
521 ideally only be one line long, but you can use multiple lines if necessary. This
522 is intended for human consumption. You do not need to make it easy for machines
525 The default is to simply return the event package name.
527 =item ($count, $directive, $reason) = $e->sets_plan()
529 Check if this event sets the testing plan. It will return an empty list if it
530 does not. If it does set the plan it will return a list of 1 to 3 items in
531 order: Expected Test Count, Test Directive, Reason for directive.
533 =item $bool = $e->diagnostics
535 True if the event contains diagnostics info. This is useful because a
536 non-verbose harness may choose to hide events that are not in this category.
537 Some formatters may choose to send these to STDERR instead of STDOUT to ensure
540 =item $bool = $e->no_display
542 False by default. This will return true on events that should not be displayed
545 =item $id = $e->in_subtest
547 If the event is inside a subtest this should have the subtest ID.
549 =item $id = $e->subtest_id
551 If the event is a final subtest event, this should contain the subtest ID.
555 =head1 THIRD PARTY META-DATA
557 This object consumes L<Test2::Util::ExternalMeta> which provides a consistent
558 way for you to attach meta-data to instances of this class. This is useful for
559 tools, plugins, and other extensions.
563 The source code repository for Test2 can be found at
564 F<http://github.com/Test-More/test-more/>.
570 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
578 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
584 Copyright 2017 Chad Granum E<lt>exodist@cpan.orgE<gt>.
586 This program is free software; you can redistribute it and/or
587 modify it under the same terms as Perl itself.
589 See F<http://dev.perl.org/licenses/>