Test2::Event - Base class for events
Base class for all event objects that get passed through Test2.
package Test2::Event::MyEvent;
use strict;
use warnings;
# This will make our class an event subclass (required)
use base 'Test2::Event';
# Add some accessors (optional)
# You are not obligated to use HashBase, you can use any object tool you
# want, or roll your own accessors.
use Test2::Util::HashBase qw/foo bar baz/;
# Use this if you want the legacy API to be written for you, for this to
# work you will need to implement a facet_data() method.
use Test2::Util::Facets2Legacy;
# Chance to initialize some defaults
sub init {
my $self = shift;
# no other args in @_
$self->set_foo('xxx') unless defined $self->foo;
...
}
# This is the new way for events to convey data to the Test2 system
sub facet_data {
my $self = shift;
# Get common facets such as 'about', 'trace' 'amnesty', and 'meta'
my $facet_data = $self->common_facet_data();
# Are you making an assertion?
$facet_data->{assert} = {pass => 1, details => 'my assertion'};
...
return $facet_data;
}
1;Get a snapshot of the Test2::EventFacet::Trace as it was when this event was generated
Check if 2 events are related. In this case related means their traces share a signature meaning they were created with the same context (or at the very least by contexts which share an id, which is the same thing unless someone is doing something very bad).
This can be used to reliably link multiple events created by the same tool. For instance a failing test like ok(0, "fail" will generate 2 events, one being a Test2::Event::Ok, the other being a Test2::Event::Diag, both of these events are related having been created under the same context and by the same initial tool (though multiple tools may have been nested under the initial one).
This will return undef if the relationship cannot be checked, which happens if either event has an incomplete or missing trace. This will return 0 if the traces are complete, but do not match. 1 will be returned if there is a match.
This can be used to add amnesty to this event. Amnesty only effects failing assertions in most cases, but some formatters may display them for passing assertions, or even non-assertions as well.
Amnesty will prevent a failed assertion from causing the overall test to fail. In other words it marks a failure as expected and allowed.
Note: This is how 'TODO' is implemented under the hood. TODO is essentially amnesty with the 'TODO' tag. The details are the reason for the TODO.
If UUID tagging is enabled (See Test::API) then any event that has made its way through a hub will be tagged with a UUID. A newly created event will not yet be tagged in most cases.
This method is used to load a facet by name (or key). It will attempt to load the facet class, if it succeeds it will return the class it loaded. If it fails it will return undef. This caches the result at the class level so that future calls will be faster.
The $name variable should be the key used to access the facet in a facets hashref. For instance the assertion facet has the key 'assert', the information facet has the 'info' key, and the error facet has the key 'errors'. You may include or omit the 's' at the end of the name, the method is smart enough to try both the 's' and no-'s' forms, it will check what you provided first, and if that is not found it will add or strip the 's and try again.
This returns a list of all facets that have been loaded using the load_facet() method. This will not return any classes that have not been loaded, or have been loaded directly without a call to load_facet().
Note: The core facet types are automatically loaded and populated in this list.
This can be used by subclasses to generate a starting facet data hashref. This will populate the hashref with the trace, meta, amnesty, and about facets. These facets are nearly always produced the same way for all events.
If you do not override this then the default implementation will attempt to generate facets from the legacy API. This generation is limited only to what the legacy API can provide. It is recommended that you override this method and write out explicit facet data.
This takes the hashref from facet_data() and blesses each facet into the proper Test2::EventFacet::* subclass. If no class can be found for any given facet it will be passed along unchanged.