diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Test2::Event.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Test2::Event.3pm | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Test2::Event.3pm b/upstream/mageia-cauldron/man3pm/Test2::Event.3pm new file mode 100644 index 00000000..8d71ee86 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Test2::Event.3pm @@ -0,0 +1,481 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Test2::Event 3pm" +.TH Test2::Event 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Test2::Event \- Base class for events +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Base class for all event objects that get passed through +Test2. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 3 +\& package Test2::Event::MyEvent; +\& use strict; +\& use warnings; +\& +\& # This will make our class an event subclass (required) +\& use base \*(AqTest2::Event\*(Aq; +\& +\& # 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(\*(Aqxxx\*(Aq) 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 \*(Aqabout\*(Aq, \*(Aqtrace\*(Aq \*(Aqamnesty\*(Aq, and \*(Aqmeta\*(Aq +\& my $facet_data = $self\->common_facet_data(); +\& +\& # Are you making an assertion? +\& $facet_data\->{assert} = {pass => 1, details => \*(Aqmy assertion\*(Aq}; +\& ... +\& +\& return $facet_data; +\& } +\& +\& 1; +.Ve +.SH METHODS +.IX Header "METHODS" +.SS GENERAL +.IX Subsection "GENERAL" +.ie n .IP "$trace = $e\->trace" 4 +.el .IP "\f(CW$trace\fR = \f(CW$e\fR\->trace" 4 +.IX Item "$trace = $e->trace" +Get a snapshot of the Test2::EventFacet::Trace as it was when this event was +generated +.ie n .IP "$bool_or_undef = $e\->related($e2)" 4 +.el .IP "\f(CW$bool_or_undef\fR = \f(CW$e\fR\->related($e2)" 4 +.IX Item "$bool_or_undef = $e->related($e2)" +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). +.Sp +This can be used to reliably link multiple events created by the same tool. For +instance a failing test like \f(CW\*(C`ok(0, "fail"\*(C'\fR 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). +.Sp +This will return \f(CW\*(C`undef\*(C'\fR if the relationship cannot be checked, which happens +if either event has an incomplete or missing trace. This will return \f(CW0\fR if +the traces are complete, but do not match. \f(CW1\fR will be returned if there is a +match. +.ie n .IP "$e\->add_amnesty({tag => $TAG, details => $DETAILS});" 4 +.el .IP "\f(CW$e\fR\->add_amnesty({tag => \f(CW$TAG\fR, details => \f(CW$DETAILS\fR});" 4 +.IX Item "$e->add_amnesty({tag => $TAG, details => $DETAILS});" +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. +.Sp +Amnesty will prevent a failed assertion from causing the overall test to fail. +In other words it marks a failure as expected and allowed. +.Sp +\&\fBNote:\fR 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. +.ie n .IP "$uuid = $e\->uuid" 4 +.el .IP "\f(CW$uuid\fR = \f(CW$e\fR\->uuid" 4 +.IX Item "$uuid = $e->uuid" +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. +.ie n .IP "$class = $e\->load_facet($name)" 4 +.el .IP "\f(CW$class\fR = \f(CW$e\fR\->load_facet($name)" 4 +.IX Item "$class = $e->load_facet($name)" +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 \f(CW\*(C`undef\*(C'\fR. This caches the result at the class level so that +future calls will be faster. +.Sp +The \f(CW$name\fR 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. +.ie n .IP "@classes = $e\->\fBFACET_TYPES()\fR" 4 +.el .IP "\f(CW@classes\fR = \f(CW$e\fR\->\fBFACET_TYPES()\fR" 4 +.IX Item "@classes = $e->FACET_TYPES()" +.PD 0 +.ie n .IP "@classes = Test2::Event\->\fBFACET_TYPES()\fR" 4 +.el .IP "\f(CW@classes\fR = Test2::Event\->\fBFACET_TYPES()\fR" 4 +.IX Item "@classes = Test2::Event->FACET_TYPES()" +.PD +This returns a list of all facets that have been loaded using the +\&\f(CWload_facet()\fR method. This will not return any classes that have not been +loaded, or have been loaded directly without a call to \f(CWload_facet()\fR. +.Sp +\&\fBNote:\fR The core facet types are automatically loaded and populated in this +list. +.SS "NEW API" +.IX Subsection "NEW API" +.ie n .IP "$hashref = $e\->\fBcommon_facet_data()\fR;" 4 +.el .IP "\f(CW$hashref\fR = \f(CW$e\fR\->\fBcommon_facet_data()\fR;" 4 +.IX Item "$hashref = $e->common_facet_data();" +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. +.ie n .IP "$hashref = $e\->\fBfacet_data()\fR" 4 +.el .IP "\f(CW$hashref\fR = \f(CW$e\fR\->\fBfacet_data()\fR" 4 +.IX Item "$hashref = $e->facet_data()" +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. +.ie n .IP "$hashref = $e\->\fBfacets()\fR" 4 +.el .IP "\f(CW$hashref\fR = \f(CW$e\fR\->\fBfacets()\fR" 4 +.IX Item "$hashref = $e->facets()" +This takes the hashref from \f(CWfacet_data()\fR and blesses each facet into the +proper \f(CW\*(C`Test2::EventFacet::*\*(C'\fR subclass. If no class can be found for any given +facet it will be passed along unchanged. +.ie n .IP "@errors = $e\->\fBvalidate_facet_data()\fR;" 4 +.el .IP "\f(CW@errors\fR = \f(CW$e\fR\->\fBvalidate_facet_data()\fR;" 4 +.IX Item "@errors = $e->validate_facet_data();" +.PD 0 +.ie n .IP "@errors = $e\->validate_facet_data(%params);" 4 +.el .IP "\f(CW@errors\fR = \f(CW$e\fR\->validate_facet_data(%params);" 4 +.IX Item "@errors = $e->validate_facet_data(%params);" +.ie n .IP "@errors = $e\->validate_facet_data(\e%facets, %params);" 4 +.el .IP "\f(CW@errors\fR = \f(CW$e\fR\->validate_facet_data(\e%facets, \f(CW%params\fR);" 4 +.IX Item "@errors = $e->validate_facet_data(%facets, %params);" +.ie n .IP "@errors = Test2::Event\->validate_facet_data(%params);" 4 +.el .IP "\f(CW@errors\fR = Test2::Event\->validate_facet_data(%params);" 4 +.IX Item "@errors = Test2::Event->validate_facet_data(%params);" +.ie n .IP "@errors = Test2::Event\->validate_facet_data(\e%facets, %params);" 4 +.el .IP "\f(CW@errors\fR = Test2::Event\->validate_facet_data(\e%facets, \f(CW%params\fR);" 4 +.IX Item "@errors = Test2::Event->validate_facet_data(%facets, %params);" +.PD +This method will validate facet data and return a list of errors. If no errors +are found this will return an empty list. +.Sp +This can be called as an object method with no arguments, in which case the +\&\f(CWfacet_data()\fR method will be called to get the facet data to be validated. +.Sp +When used as an object method the \f(CW\*(C`\e%facet_data\*(C'\fR argument may be omitted. +.Sp +When used as a class method the \f(CW\*(C`\e%facet_data\*(C'\fR argument is required. +.Sp +Remaining arguments will be slurped into a \f(CW%params\fR hash. +.Sp +Currently only 1 parameter is defined: +.RS 4 +.ie n .IP "require_facet_class => $BOOL" 4 +.el .IP "require_facet_class => \f(CW$BOOL\fR" 4 +.IX Item "require_facet_class => $BOOL" +When set to true (default is false) this will reject any facets where a facet +class cannot be found. Normally facets without classes are assumed to be custom +and are ignored. +.RE +.RS 4 +.RE +.PP +\fIWHAT ARE FACETS?\fR +.IX Subsection "WHAT ARE FACETS?" +.PP +Facets are how events convey their purpose to the Test2 internals and +formatters. An event without facets will have no intentional effect on the +overall test state, and will not be displayed at all by most formatters, except +perhaps to say that an event of an unknown type was seen. +.PP +Facets are produced by the \f(CWfacet_data()\fR subroutine, which you should +nearly-always override. \f(CWfacet_data()\fR is expected to return a hashref where +each key is the facet type, and the value is either a hashref with the data for +that facet, or an array of hashrefs. Some facets must be defined as single +hashrefs, some must be defined as an array of hashrefs, No facets allow both. +.PP +\&\f(CWfacet_data()\fR \fBMUST NOT\fR bless the data it returns, the main hashref, and +nested facet hashrefs \fBMUST\fR be bare, though items contained within each +facet may be blessed. The data returned by this method \fBshould\fR also be copies +of the internal data in order to prevent accidental state modification. +.PP +\&\f(CWfacets()\fR takes the data from \f(CWfacet_data()\fR and blesses it into the +\&\f(CW\*(C`Test2::EventFacet::*\*(C'\fR packages. This is rarely used however, the EventFacet +packages are primarily for convenience and documentation. The EventFacet +classes are not used at all internally, instead the raw data is used. +.PP +Here is a list of facet types by package. The packages are not used internally, +but are where the documentation for each type is kept. +.PP +\&\fBNote:\fR Every single facet type has the \f(CW\*(Aqdetails\*(Aq\fR field. This field is +always intended for human consumption, and when provided, should explain the +\&'why' for the facet. All other fields are facet specific. +.IP "about => {...}" 4 +.IX Item "about => {...}" +Test2::EventFacet::About +.Sp +This contains information about the event itself such as the event package +name. The \f(CW\*(C`details\*(C'\fR field for this facet is an overall summary of the event. +.IP "assert => {...}" 4 +.IX Item "assert => {...}" +Test2::EventFacet::Assert +.Sp +This facet is used if an assertion was made. The \f(CW\*(C`details\*(C'\fR field of this facet +is the description of the assertion. +.IP "control => {...}" 4 +.IX Item "control => {...}" +Test2::EventFacet::Control +.Sp +This facet is used to tell the Test2::Event::Hub about special actions the +event causes. Things like halting all testing, terminating the current test, +etc. In this facet the \f(CW\*(C`details\*(C'\fR field explains why any special action was +taken. +.Sp +\&\fBNote:\fR This is how bail-out is implemented. +.IP "meta => {...}" 4 +.IX Item "meta => {...}" +Test2::EventFacet::Meta +.Sp +The meta facet contains all the meta-data attached to the event. In this case +the \f(CW\*(C`details\*(C'\fR field has no special meaning, but may be present if something +sets the 'details' meta-key on the event. +.IP "parent => {...}" 4 +.IX Item "parent => {...}" +Test2::EventFacet::Parent +.Sp +This facet contains nested events and similar details for subtests. In this +facet the \f(CW\*(C`details\*(C'\fR field will typically be the name of the subtest. +.IP "plan => {...}" 4 +.IX Item "plan => {...}" +Test2::EventFacet::Plan +.Sp +This facet tells the system that a plan has been set. The \f(CW\*(C`details\*(C'\fR field of +this is usually left empty, but when present explains why the plan is what it +is, this is most useful if the plan is to skip-all. +.IP "trace => {...}" 4 +.IX Item "trace => {...}" +Test2::EventFacet::Trace +.Sp +This facet contains information related to when and where the event was +generated. This is how the test file and line number of a failure is known. +This facet can also help you to tell if tests are related. +.Sp +In this facet the \f(CW\*(C`details\*(C'\fR field overrides the "failed at test_file.t line +42." message provided on assertion failure. +.IP "amnesty => [{...}, ...]" 4 +.IX Item "amnesty => [{...}, ...]" +Test2::EventFacet::Amnesty +.Sp +The amnesty facet is a list instead of a single item, this is important as +amnesty can come from multiple places at once. +.Sp +For each instance of amnesty the \f(CW\*(C`details\*(C'\fR field explains why amnesty was +granted. +.Sp +\&\fBNote:\fR Outside of formatters amnesty only acts to forgive a failing +assertion. +.IP "errors => [{...}, ...]" 4 +.IX Item "errors => [{...}, ...]" +Test2::EventFacet::Error +.Sp +The errors facet is a list instead of a single item, any number of errors can +be listed. In this facet \f(CW\*(C`details\*(C'\fR describes the error, or may contain the raw +error message itself (such as an exception). In perl exception may be blessed +objects, as such the raw data for this facet may contain nested items which are +blessed. +.Sp +Not all errors are considered fatal, there is a \f(CW\*(C`fail\*(C'\fR field that must be set +for an error to cause the test to fail. +.Sp +\&\fBNote:\fR This facet is unique in that the field name is 'errors' while the +package is 'Error'. This is because this is the only facet type that is both a +list, and has a name where the plural is not the same as the singular. This may +cause some confusion, but I feel it will be less confusing than the +alternative. +.IP "info => [{...}, ...]" 4 +.IX Item "info => [{...}, ...]" +Test2::EventFacet::Info +.Sp +The 'info' facet is a list instead of a single item, any quantity of extra +information can be attached to an event. Some information may be critical +diagnostics, others may be simply commentary in nature, this is determined by +the \f(CW\*(C`debug\*(C'\fR flag. +.Sp +For this facet the \f(CW\*(C`details\*(C'\fR flag is the info itself. This info may be a +string, or it may be a data structure to display. This is one of the few facet +types that may contain blessed items. +.SS "LEGACY API" +.IX Subsection "LEGACY API" +.ie n .IP "$bool = $e\->causes_fail" 4 +.el .IP "\f(CW$bool\fR = \f(CW$e\fR\->causes_fail" 4 +.IX Item "$bool = $e->causes_fail" +Returns true if this event should result in a test failure. In general this +should be false. +.ie n .IP "$bool = $e\->increments_count" 4 +.el .IP "\f(CW$bool\fR = \f(CW$e\fR\->increments_count" 4 +.IX Item "$bool = $e->increments_count" +Should be true if this event should result in a test count increment. +.ie n .IP $e\->callback($hub) 4 +.el .IP \f(CW$e\fR\->callback($hub) 4 +.IX Item "$e->callback($hub)" +If your event needs to have extra effects on the Test2::Hub you can override +this method. +.Sp +This is called \fBBEFORE\fR your event is passed to the formatter. +.ie n .IP "$num = $e\->nested" 4 +.el .IP "\f(CW$num\fR = \f(CW$e\fR\->nested" 4 +.IX Item "$num = $e->nested" +If this event is nested inside of other events, this should be the depth of +nesting. (This is mainly for subtests) +.ie n .IP "$bool = $e\->global" 4 +.el .IP "\f(CW$bool\fR = \f(CW$e\fR\->global" 4 +.IX Item "$bool = $e->global" +Set this to true if your event is global, that is ALL threads and processes +should see it no matter when or where it is generated. This is not a common +thing to want, it is used by bail-out and skip_all to end testing. +.ie n .IP "$code = $e\->terminate" 4 +.el .IP "\f(CW$code\fR = \f(CW$e\fR\->terminate" 4 +.IX Item "$code = $e->terminate" +This is called \fBAFTER\fR your event has been passed to the formatter. This +should normally return undef, only change this if your event should cause the +test to exit immediately. +.Sp +If you want this event to cause the test to exit you should return the exit +code here. Exit code of 0 means exit success, any other integer means exit with +failure. +.Sp +This is used by Test2::Event::Plan to exit 0 when the plan is +\&'skip_all'. This is also used by Test2::Event:Bail to force the test +to exit with a failure. +.Sp +This is called after the event has been sent to the formatter in order to +ensure the event is seen and understood. +.ie n .IP "$msg = $e\->summary" 4 +.el .IP "\f(CW$msg\fR = \f(CW$e\fR\->summary" 4 +.IX Item "$msg = $e->summary" +This is intended to be a human readable summary of the event. This should +ideally only be one line long, but you can use multiple lines if necessary. This +is intended for human consumption. You do not need to make it easy for machines +to understand. +.Sp +The default is to simply return the event package name. +.ie n .IP "($count, $directive, $reason) = $e\->\fBsets_plan()\fR" 4 +.el .IP "($count, \f(CW$directive\fR, \f(CW$reason\fR) = \f(CW$e\fR\->\fBsets_plan()\fR" 4 +.IX Item "($count, $directive, $reason) = $e->sets_plan()" +Check if this event sets the testing plan. It will return an empty list if it +does not. If it does set the plan it will return a list of 1 to 3 items in +order: Expected Test Count, Test Directive, Reason for directive. +.ie n .IP "$bool = $e\->diagnostics" 4 +.el .IP "\f(CW$bool\fR = \f(CW$e\fR\->diagnostics" 4 +.IX Item "$bool = $e->diagnostics" +True if the event contains diagnostics info. This is useful because a +non-verbose harness may choose to hide events that are not in this category. +Some formatters may choose to send these to STDERR instead of STDOUT to ensure +they are seen. +.ie n .IP "$bool = $e\->no_display" 4 +.el .IP "\f(CW$bool\fR = \f(CW$e\fR\->no_display" 4 +.IX Item "$bool = $e->no_display" +False by default. This will return true on events that should not be displayed +by formatters. +.ie n .IP "$id = $e\->in_subtest" 4 +.el .IP "\f(CW$id\fR = \f(CW$e\fR\->in_subtest" 4 +.IX Item "$id = $e->in_subtest" +If the event is inside a subtest this should have the subtest ID. +.ie n .IP "$id = $e\->subtest_id" 4 +.el .IP "\f(CW$id\fR = \f(CW$e\fR\->subtest_id" 4 +.IX Item "$id = $e->subtest_id" +If the event is a final subtest event, this should contain the subtest ID. +.SH "THIRD PARTY META-DATA" +.IX Header "THIRD PARTY META-DATA" +This object consumes Test2::Util::ExternalMeta which provides a consistent +way for you to attach meta-data to instances of this class. This is useful for +tools, plugins, and other extensions. +.SH SOURCE +.IX Header "SOURCE" +The source code repository for Test2 can be found at +\&\fIhttp://github.com/Test\-More/test\-more/\fR. +.SH MAINTAINERS +.IX Header "MAINTAINERS" +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.SH AUTHORS +.IX Header "AUTHORS" +.PD 0 +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.PD +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 Chad Granum <exodist@cpan.org>. +.PP +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. +.PP +See \fIhttp://dev.perl.org/licenses/\fR |