Test::S...tBuilder(3)

📦

version 1.302027 · 2 versions

1.302027 · fedora 43 (latest)
1.302027 · fedora 44

🌸 NAME 🌸

okay so bestie, this is Test::Stream::Manual::FromTestBuilder — the little translation doc for anyone moving over from Test::More, Test::Simple, or any other Test::Builder-based tool. it hangs out in the Test::S...tBuilder(3) man page section, slay 💅

💖 DESCRIPTION 💖

this doc covers the stuff that actually matters to you if you're switching off Test::More, Test::Simple, and all those other Test::Builder-based tools. we're approaching it like you're converting an old test file, or writing a fresh one. and instead of loading Test::More, you load Test::Stream with the 'Classic' bundle:

use Test::Stream -Classic;

...

not feeling the loader life? you can load the classic bundle directly, no problem:

use Test::Stream::Bundle::Classic;

...

the 'Classic' bundle is for people who already know Test::More and are NOT looking to change how they do things. no cap. but also, lowkey, go peek at the 'V1' bundle, Test::Stream::Bundle::V1, and see if that one hits different for you 👀

✨ WHAT IS (MOSTLY) THE SAME? ✨

this is the list of stuff that either didn't change at all, or changed in ways you're probably not even gonna notice.

🫶 FUNCTIONS

ok — the signature is different, bestie. instead of ok($$;$), it's now ok($$;$@). that slurpy @ lets you tack on diagnostics messages that only show up if the test fails. so you can attach your custom diagnostics directly onto a failing test. iconic.

Defined in Test::Stream::Plugin::Core.

is — barely anything changed in how you use it, but there's a LOT going on under the hood, and the signature changed just like ok()'s: you can add diagnostics at the end to display in case of failure.

this function stringifies the first 2 arguments and runs a string comparison. if both arguments are undefined, that also counts as a pass.

isnt — very little has changed, same changes as is().
is_deeply — very little changed in how you use it, but a lot changed under the hood, and the signature got the same glow-up as ok()'s, meaning you can add diagnostics at the end to display in case of failure.

this function does a deep comparison, recursing into hashrefs, arrayrefs, and scalar refs. any other values get compared with string comparisons.

diagnostics got better too — you get a table with all the differences between the structures. normally it stops at 25 differences, but you can tweak that number with the $ENV{TS_MAX_DELTA} environment variable.

note: under the hood this uses the Test::Stream::Compare library, so it will gladly accept any advanced check objects you produce with that library. in practice this has no effect on you at all unless you use the Compare library tools directly.

like — not much has changed, added @ to the signature for diagnostics.
unlike — not much has changed, added @ to the signature for diagnostics.
diag — no differences 💯

Defined in Test::Stream::Plugin::Core.

note — no differences 💯

Defined in Test::Stream::Plugin::Core.

pass — no differences 💯

Defined in Test::Stream::Plugin::Core.

fail — signature changed from fail($) to fail($;@). the extra arguments are diagnostics that get shown alongside your failing test.

Defined in Test::Stream::Plugin::Core.

done_testing — no longer accepts arguments. most people didn't even know it could accept arguments in Test::More, so this is unlikely to affect many of y'all.

Defined in Test::Stream::Plugin::Core.

BAIL_OUT — no differences 💯

Defined in Test::Stream::Plugin::Core.

skip — no differences 💯

Defined in Test::Stream::Plugin::Core.

can_ok — no differences 💯

Defined in Test::Stream::Plugin::Core.

🌈 BEHAVIOR

TAP is still the default output format.
you get similar, if not identical, diagnostics at the end of a failing test file.
you get file and line number for failed tests.

💀 WHAT IS (SIGNIFICANTLY) DIFFERENT? 💀

this is the list of very notable changes that are gonna hurt you if you're not aware of them. forewarned is forearmed, bestie.

🔥 FUNCTIONS

plan — only accepts a number of tests expected to be run.

plan 5;

see "skip_all" for skipping an entire test.

Defined in Test::Stream::Plugin::Core.

skip_all — this is the new way to skip an entire test, and it takes a reason as its argument.

skip_all 'Broken for now';

Defined in Test::Stream::Plugin::Core.

isa_ok — people used to use this incorrectly in Test::More all the time. it was reasonable to assume it worked like can_ok and accepted several package names. instead, the Test::More implementation used the third argument as an alternate name for the first. that's been changed so it's consistent with can_ok and similar tools now.

isa_ok($thing, 'My::Class', 'My::Subclass', ...);

Defined in Test::Stream::Plugin::Core.

subtest — the default output has been changed:

ok 1 - Subtest Name {
    ok 1 - subtest result
    ok 2 - another result
    1..2
# }

the old output format is still available if you ask for it:

use Test::Stream '-Classic', 'Subtest' => ['streamed'];

Defined in Test::Stream::Plugin::Subtest.

cmp_ok — usage is still the same. internals got heavily modified to enhance diagnostics. there's also now a list of supported operators, and warnings get issued if you use an unsupported one.

Defined in Test::Stream::Plugin::Core.

🙈 WHAT IS COMPLETELY GONE? 🙈

these are no longer around for you to use. gone, not forgotten, periodt.

🎀 FUNCTIONS

use_ok
require_ok

errors loading modules cause the test to die anyway, so just load them — if they don't work, the test will fail. making a separate API for this is a wasted effort. also, doing it that way requires the functions to guess whether you gave a module name or a filename, and then munge the input to figure out what actually needs to be loaded. messy.

new_ok — this is easy enough on your own:

ok(my $one = $class->new(@args), "NAME");

the utility of new_ok() is questionable at best, ngl.

eq_array
eq_hash
eq_set

Test::More itself discourages you from using these, so we're not carrying them forward. byeee 👋

explain — this method was copied in an API-incompatible way from Test::Most. that created an incompatibility issue between the 2 libraries and made a real mess of things. there IS value in a tool like this, but if it gets added, it'll be added under a new name to avoid conflicts.

💜 VARIABLES

$TODO — the $TODO variable is completely gone. do not use it. instead we have the todo() function. there are 2 ways to use it:

similar to the old way:

TODO: {
    # Note, this is a lexical variable, not a package variable. Do not use
    # local. The todo will end when the variable is destroyed (at the end
    # of the scope, or when you assign something else, such as undef, to
    # the variable.
    my $todo = todo "These are not ready yet";

    ok(0, 'todo');
}

another way:

todo 'These are not ready yet' => sub {
    ok(0, 'todo');
};

$Test::Builder::Level — see Test::Stream::Context for how <Test:Stream> solves the same problem.

🦋 BEHAVIOR

plan at import — "done_testing" is the preferred way to plan. but if you really want a plan, you can use the plan() or "skip_all" functions. setting the plan at compile time caused bugs in the past (primarily with subtests that loaded external files), and moving away from that API shortcut helps make things cleaner.

👑 WHAT ELSE DO I GET? 👑

here's some new stuff you get for free! no extra charge, you're welcome.

⭐ FUNCTIONS

DOES_ok — just like "isa_ok" and "can_ok" except it checks "DOES" instead of "can" or "isa". all caps is used to reflect the UNIVERSAL property being used, and it also helps avoid conflicts with Moose-related stuff.

Defined in Test::Stream::Plugin::Core.

ref_ok — checks that something is a ref, and optionally that it's a specific type of ref.

Defined in Test::Stream::Plugin::Core.

imported_ok — checks that the current namespace has the specified functions. this will NOT find inherited methods, only subs actually defined in the current namespace. and it will NOT check that the subs came from another package.

this is a better alternative to "can_ok" when you're testing imports.

Defined in Test::Stream::Plugin::Core.

not_imported_ok — checks that the specified functions are NOT available in the current namespace. it ignores inherited methods, and only looks for subs in the current namespace.

Defined in Test::Stream::Plugin::Core.

ref_is — checks that 2 references are the same references. this is not a deep check, it compares the addresses of the 2 provided refs. will fail if either argument is not a reference, or is undef.

Defined in Test::Stream::Plugin::Core.

ref_is_not — checks that 2 references are NOT the same references. not a deep check, it compares the addresses of the 2 provided refs. will fail if either argument is not a reference, or is undef.

Defined in Test::Stream::Plugin::Core.

set_encoding — can be used to set the encoding of TAP, and possibly other formatters too.

use Test::Stream -Classic;
use utf8;

set_encoding 'utf8';
# No wide character warnings
ok(1, '†');

Defined in Test::Stream::Plugin::Core.

🧚 BEHAVIOR

Forking/Threading support — forking and threading in your tests will just work (so long as you use the 'IPC' plugin, which is included in the 'Classic' bundle). yes, really, it just works 💅

🍓 SOURCE 🍓

the source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/.

💖 MAINTAINERS 💖

Chad Granum <exodist@cpan.org>

🌸 AUTHORS 🌸

Chad Granum <exodist@cpan.org>

💅 COPYRIGHT 💅

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 was Test::S...tBuilder(3) from the perl v5.42.0 docs, dated 2025-07-25 — go write some tests, you're gonna eat 💖✨

📦 where this page comes from

fedora 43: perl-Test-Stream 1.302027-35.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms