The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Simple-1.301001_106
River stage five • 22891 direct dependents • 32646 total dependents
190 ++
/ Test::Stream::Event

NAME

Test::Stream::Event - Base class for events

DESCRIPTION

Base class for all event objects that get passed through Test::Stream.

SYNOPSIS

    package Test::Stream::Event::MyEvent;
    use strict;
    use warnings;

    # This will make our class an event subclass, add the specified accessors,
    # add constants for all our fields, and fields we inherit.
    use Test::Stream::Event(
        accessors  => [qw/foo bar baz/],
    );

    # Chance to initialize some defaults
    sub init {
        my $self = shift;
        # no other args in @_

        $self->SUPER::init();

        $self->set_foo('xxx') unless defined $self->foo;

        # Events are arrayrefs, all accessors have a constant defined with
        # their index.
        $self->[BAR] ||= "";

        ...
    }

    # If your event produces TAP output it must define this method
    sub to_tap {
        my $self = shift;
        return (
            # Constants are defined at import, all are optional, and may appear
            # any number of times.
            [OUT_STD, $self->foo],
            [OUT_ERR, $self->bar],
            [OUT_STD, $self->baz],
        );
    }

    # This is your hook to add details to the summary fields.
    sub extra_details {
        my $self = shift;

        my @super_details = $self->SUPER::extra_details();

        return (
            @super_details,

            foo => $self->foo || undef,
            bar => $self->bar || '',
            ...
        );
    }

    1;

And to use it:

    my $ctx = context();
    $ctx->send_event('MyEvent', foo => 1, baz => 2);

IMPORTING

ARGUMENTS

In addition to the arguments listed here, you may pass in any arguments accepted by Test::Stream::HashBase.

base => $BASE_CLASS

This lets you specify an event class to subclass. THIS MUST BE AN EVENT CLASS. If you do not specify anything here then Test::Stream::Event will be used.

accessors => \@FIELDS

This lets you define any fields you wish to be present in your class. This is the only way to define storage for your event. Each field specified will get a read-only accessor with the same name as the field, as well as a setter set_FIELD(). You will also get a constant that returns the index of the field in the classes arrayref. The constant is the name of the field in all upper-case.

SUBCLASSING

Test::Stream::Event is added to your @INC for you, unless you specify an alternative base class, which must itself subclass Test::Stream::Event.

Events CAN NOT use multiple inheritance in most cases. This is mainly because events are arrayrefs and not hashrefs. Each subclass must add fields as new indexes after the last index of the parent class.

METHODS

$ctx = $e->context

Get a snapshot of the context as it was when this event was generated

$call = $e->created

Get the caller() details from when the objects was created. This is usually the call to the tool that generated the event such as Test::More::ok().

$bool = $e->in_subtest

Check if the event was generated within a subtest.

$encoding = $e->encoding

Get the encoding that was in effect when the event was generated

@details = $e->extra_details

Get an ordered key/value pair list of summary fields for the event. Override this to add additional fields.

@summary = $e->summary

Get an ordered key/value pair list of summary fields for the event, including parent class fields. In general you should not override this as it has a useful (thought not depended upon) order.

SUMMARY FIELDS

These are the fields that will be present when calling my %sum = $e->summary. Please note that the fields are returned as an order key+pair list, they can be directly assigned to a hash if desired, or they can be assigned to an array to preserver the order. The order is as it appears below, NOT alphabetical.

type

The name of the event type, typically this is the lowercase form of the last part of the class name.

package

The package that generated this event.

file

The file in which the event was generated, and to which errors should be attributed.

line

The line number on which the event was generated, and to which errors should be attributed.

tool_package

The package that provided the tool that generated the event (example: Test::More)

tool_name

The name of the sub that produced the event (examples: ok(), is()).

encoding

The encoding that should be used when printing the TAP output from this event.

in_todo

True if the event was generated while TODO was in effect.

todo

The todo message if the event was generated with TODO in effect.

pid

The PID in which the event was generated.

skip

The skip message if the event was generated via skip.

SOURCE

The source code repository for Test::More can be found at http://github.com/Test-More/test-more/.

MAINTAINER

Chad Granum <exodist@cpan.org>

AUTHORS

The following people have all contributed to the Test-More dist (sorted using VIM's sort function).

Chad Granum <exodist@cpan.org>
Fergal Daly <fergal@esatclear.ie>>
Mark Fowler <mark@twoshortplanks.com>
Michael G Schwern <schwern@pobox.com>
唐鳳

COPYRIGHT

There has been a lot of code migration between modules, here are all the original copyrights together:

Test::Stream
Test::Stream::Tester

Copyright 2015 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

Test::Simple
Test::More
Test::Builder

Originally authored by Michael G Schwern <schwern@pobox.com> with much inspiration from Joshua Pritikin's Test module and lots of help from Barrie Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa gang.

Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern <schwern@pobox.com>, wardrobe by Calvin Klein.

Copyright 2001-2008 by Michael G Schwern <schwern@pobox.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

Test::use::ok

To the extent possible under law, 唐鳳 has waived all copyright and related or neighboring rights to Test-use-ok.

This work is published from Taiwan.

http://creativecommons.org/publicdomain/zero/1.0

Test::Tester

This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some parts are based on other people's work.

Under the same license as Perl itself

See http://www.perl.com/perl/misc/Artistic.html

Test::Builder::Tester

Copyright Mark Fowler <mark@twoshortplanks.com> 2002, 2004.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.