Test::S...:Tooling(3)

📦
version 1.302027 · 2 versions
, in fedora 43

💖 Test::S...:Tooling 💖

okay so bestie, this is the Test::S...:Tooling(3) page from the User Contributed Perl Documentation collection, and it's literally your whole guide to writing your own test tools with Test::Stream. pull up a chair, grab a boba, we're doing this. 🧋✨

✨ NAME ✨

Test::Stream::Manual::Tooling — How to write test tools using the Test::Stream infrastructure. 🛠️💅

🌸 DESCRIPTION 🌸

This manual page explains the process of building a test tool using Test::Stream. no cap, that's the whole vibe. 🦋

🎀 QUICK START 🎀

If you wanted to write a module that implemented the ok() function, this is all you need to write, fr fr:

package Test::Stream::Plugin::MyOk;
use strict;
use warnings;

use Test::Stream::Context qw/context/;

use Test::Stream::Exporter;
default_exports qw/ok/;
no Test::Stream::Exporter;

sub ok($;$) {
    my ($bool, $name) = @_;    # Get args

    my $ctx = context();       # Obtain a context

    $ctx->ok($bool, $name);    # Issue an OK event

    $ctx->release;             # Release the context

    return $bool;              # Return the true/false
}

1;

like. that's IT. iconic behavior. 👑

🔍 EXPLANATION 🔍

💫 Obtaining a context

This is the MOST critical thing you need to do in any testing tool. You should do this as soon as possible. The Test::Stream::Context object ties everything together. Obtaining a context object locks in the file and line number to which errors should be reported. It also finds the current hub to which all events should be sent. Finally the context object is the primary interface used to generate events. In short the context object is the tool builders 1-stop shop. 🛍️

✅ Issue an Ok event

The core event types, "ok", "note", "diag", "bail", and "plan" have shortcut functions on the context object. These shortcut functions construct the event, and send it to the hub for processing. Other event types can be generated as well using the "$ctx->build_event(...)" or "$ctx->send_event(...)" methods. See the Test::Stream::Context object documentation for additional details. 📬

🫧 Release the context

When your tool is finished it is very important that you release the context. Failing to release the context would result in a leak condition. In most cases the context will detect this condition and take measures to correct it, along with issuing a very verbose warning.

bestie. release your context. the leak is not cute, the warning is LOUD, and nobody wants that energy. 😭

🔁 Return the true/false

Typically testing tools will return a true or false indicating if the test has passed or failed. simple as. ✨

🔥 ADVANCED 🔥

This covers more advanced topics for tool builders. buckle up, we're going deeper 💜

🌈 EVENTS 🌈

Most testing tools generate events. The most common event generated is the Test::Stream::Event::Ok event. In addition it is possible for tools to create their own event types. go off, invent things 💅

🧠 CONTEXT 🧠

The Test::Stream::Context object ties everything together. Obtaining a context object locks in the file and line number to which errors should be reported. It also finds the current hub to which all events should be sent. Finally the context object is the primary interface used to generate events. In short the context object is the tool builders 1-stop shop. 🛒

There is only ever one canonical context instance per active hub. If two tools try to obtain a context in the same stack they will both get the same one, the first one to request it generates it, the second gets the existing instance. In both cases the tool MUST release it when done. Tools should never send contexts to other tools, and they should never accept them as arguments. Tools that get broken up into multiple functions may pass the context to their component subs.

so like, you can pass it down to your own lil helper subs, but you do NOT trade contexts with other tools. that's the rule. 🤝

🐛 DEBUGINFO 🐛

Test::Stream::DebugInfo objects are stored inside the context object, its job is to store filename and line number for errors. It can also be used to issue warnings and throw exceptions. Every event generated needs to have a DebugInfo object, typically cloned from the one in the context object. 📋

🚚 HUBS 🚚

Test::Stream::Hub objects are responsible for 2 things, the first is tracking state. Hubs have an instance of an Test::Stream::State object. When an event is processed by a hub the state will be updated accordingly.

The second job of a hub is to make sure events get to the right place. Typically this means processing the event through any 'filters', then handing them off to the formatter, then finally running them through 'listeners'. 📦➡️🎨➡️👂

When IPC is active the hub will use the IPC driver (See Test::Stream::IPC) to send events to the correct process or thread. 🌐

🥞 HUB STACK 🥞

There is a single canonical Test::Stream::Stack instance tracked by the Test::Stream::Sync package. When a context is obtained it will reference whatever hub is on the top of the stack at the time it is created. Typically all events will be sent to the topmost hub. 🎯

🔄 SYNC 🔄

The Test::Stream::Sync package is the place where all shared state is tracked. Part of Test::Streams design is reducing shared state to the bare minimum. This class is kept as small as possible while still achieving the necessary functionality. The sync package tracks IPC drivers, formatter, the hub stack, and some global hooks. smol but mighty 🐜💪

📤 EXPORTER 📤

Test::Stream::Exporter is an export tool built-in to Test::Stream. Test::Stream requires export functionality well beyond what Exporter.pm is able to provide. In addition a plugin that does not need special import functionality can simply use Test::Stream::Exporter to work as a plugin. 🎁

🕵️ CAPABILITIES 🕵️

Test::Stream::Capabilities can be used to guage the active systems fork and/or thread support levels. (yes, "guage" — we're keeping it exactly how the original spells it, no edits bestie 💖)

🧰 UTILITIES 🧰

The Test::Stream::Util package exports many useful functions for test authors. 🧰✨

🔌 PLUGINS 🔌

Plugins can either use Test::Stream::Export or they can use Test::Stream::Plugin and implement the load_ts_plugin() method. pick your fighter 💅

🎁 BUNDLES 🎁

Bundles are used to combine several plugins into a single module that can be used to load them all at once. This is the better alternative to the Test::Builder practice of having tools load eachother. one import, whole squad 🫶

📚 SOURCE 📚

The source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/. go star it, go read it 👀⭐

👑 MAINTAINERS 👑

  • Chad Granum <exodist@cpan.org>

🌟 AUTHORS 🌟

  • Chad Granum <exodist@cpan.org>

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/

and that's the whole page, bestie!! 💜 this little cutie comes to you from perl v5.42.0, dated 2025-07-25, and it lives under the name Test::S...:Tooling(3). mwah 💋 go write a test tool, you're gonna slay 🌈🦋✨

📦 where this page comes from