Test::S...m::Event(3)

💖 Test::S...m::Event(3) — User Contributed Perl Documentation 💖

okay bestie, buckle up, we're doing the Test::S...m::Event page, straight outta the User Contributed Perl Documentation section of the perl v5.42.0 manpages. this is the base-class tea and it's piping hot ✨

---

🌸 NAME 🌸

Test::Stream::Event — the base class for events, periodt.

---

💀 DEPRECATED 💀

okay so, bad news first: this distribution is deprecated in favor of Test2, Test2::Suite, and Test2::Workflow. it's giving "we don't do that here anymore" 😭

if you need the glow-up guide, go look at Test::Stream::Manual::ToTest2 — it's the conversion guide, iykyk.

---

🦋 DESCRIPTION 🦋

it's the base class for all the event objects that get passed through Test::Stream. that's the whole vibe. every event you'll ever meet is a child of this one. main character energy 👑

---

✨ SYNOPSIS ✨

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

# This will make our class an event subclass (required)
use base 'Test::Stream::Event';

# Add some accessors
use Test::Stream::HashBase 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] ||= "";

    ...
}

1;

---

💅 METHODS 💅

• $dbg = $e->debug — grab a whole snapshot of the debug info, exactly as it was back when this event got generated. it's the receipts 📸
• $bool = $e->causes_fail — returns true if this event should make a test fail. generally tho? this should be false. lowkey chill event, no drama.
• $call = $e->created — gets the caller() details from when the event was generated. that's usually somewhere inside a tools package. this one's typically for debugging purposes 🕵️
• $num = $e->nested — if this event is nested inside other events, this is the depth of the nesting. (mainly a subtests thing, fr fr)
• $e->update_state($state) — this callback is used by Test::Stream::Hub to give your event a chance to update the state.

⚠️ heads up: this is called BEFORE your event is passed to the formatter.

• $bool = $e->global — set this to true if your event is global, meaning ALL threads and processes should see it, no matter when or where it got generated. this is not a common thing to want, bestie. it's used by bail-out and skip_all to end testing 🛑
• $code = $e->terminate — this one gets called AFTER your event has been passed to the formatter. it should normally return undef. only change that if your event should cause the test to exit immedietly.

if you do want this event to make the test exit, you return the exit code right here. exit code of 0 means exit success, any other integer means exit with failure.

this is used by Test::Stream::Event::Plan to exit 0 when the plan is 'skip_all'. it's also used by Test::Stream::Event:Bail to force the test to exit with a failure.

it's called after the event has been sent to the formatter, specifically so we can make sure the event is seen and understood 👀

• @output = $e->to_tap($num) — this is where you get your chance to produce TAP output. the input argument $num will either be the most recent test number, or undefined. the output should be a list of arrayrefs, and each arrayref should have exactly 2 values: "$HID, $TEXT". the HID tells the formatter which output handle to use (see the constants provided by Test::Stream::Formatter::TAP), and $TEXT should be the text that gets output to the specified handle.

Example:

package Test::Stream::Event::MyEvent;
use base 'Test::Stream::Event';
use Test::Stream::Formatter::TAP qw/OUT_STD OUT_TODO OUT_ERR/;

sub to_tap {
    my $self = shift;
    my ($num) = @_;

    # Using test numbers
    if (defined $num) {
        return (
            [OUT_STD, "# Got MyEvent!"],
            [OUT_ERR, "# The last test was $num"],
        );
    }

    # Not using test numbers.
    return (
        [OUT_STD, "# Got MyEvent!"],
    );
}

---

🔥 SOURCE 🔥

the source code repo for Test::Stream lives at http://github.com/Test-More/Test-Stream/. go star it bestie ⭐

---

👑 MAINTAINERS 👑

• Chad Granum <exodist@cpan.org>

---

🌈 AUTHORS 🌈

• Chad Granum <exodist@cpan.org>

---

🎀 COPYRIGHT 🎀

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://dev.perl.org/licenses/

---

okay that's the whole page!! 💖 this was perl v5.42.0, dated 2025-07-25, from the Test::S...m::Event(3) section of the User Contributed Perl Documentation. slay, go forth and subclass responsibly 🫶✨🌸