Test::S...n::Core(3)

💖 Test::Stream::Plugin::Core 💖

okay so quick vibe check before we dive in: this is the manpage for Test::Stream::Plugin::Core, and it lives in section 3 of the User Contributed Perl Documentation. that's the whole "Test::S...n::Core(3)" thing at the top of the page, bestie — mystery solved 🕵️♀️✨

---

🌸 NAME 🌸

Test::Stream::Plugin::Core — the Test::Stream implementation of the core testing tools. like, the actual testing bread and butter. iconic behavior only 👑

---

💀 DEPRECATED 💀

bestie. sit down. 😭

This distribution is deprecated in favor of Test2, Test2::Suite, and Test2::Workflow.

If you need the conversion guide, go look at Test::Stream::Manual::ToTest2. it's giving "moving on era" 🦋

---

📝 DESCRIPTION 📝

First things first, and I need you to hear me on this one:

This is not a drop-in replacement for Test::More. 💅

It's the new testing library that's meant to replace Test::More. This library is built directly on new internals instead of Test::Builder.

It implements most of the same functionality as Test::More, but since switching over from Test::More is not automatic, some incompatible API changes have been made. So if you decide to swap Test::More out of your existing test files, you may have to update some function calls. no cap, read the errors, they're telling you something 🌈

---

✨ SYNOPSIS ✨

here's the whole vibe, copy-paste ready:

use Test::Stream qw/Core/;

set_encoding('utf8');

plan($num); # Optional, set a plan

use Data::Dumper;
imported_ok qw/Dumper/;
not_imported_ok qw/dumper/;

# skip all tests in some condition
skip_all("do not run") if $cond;

if ($passing) {
    pass('a passing test');
}
else {
    fail('a failing test');
}

ok($x, "simple test");

# Check that the class or object has the specified methods defined.
can_ok($class_or_obj, @methods);

# Check that the class or object is or subclasses the specified packages
isa_ok($class_or_obj, @packages);

# Check that the class or object consumes the specified roles.
DOES_ok($class_or_obj, @roles);

# Check that $ref is a HASH reference
ref_ok($ref, 'HASH', 'Must be a hash')

# The preferred way to plan
done_testing;

---

🎀 EXPORTS 🎀

All subs are exported by default. every single one, you don't have to ask. we love a generous queen 🫶

🔥 ASSERTIONS 🔥

• ok($bool), ok($bool, $name), ok($bool, $name, @diag) — the simple assertion, the moment of truth. if $bool is true the test passes, if it's false the test fails. the test name is optional, and all arguments after the name get added as diagnostics messages if and only if the test fails. if the test passes, all those diagnostics arguments are just ignored. they get no screen time 💅
• pass(), pass($name) — fire off a passing test (a single Ok event). name is optional, but cute to have ⭐
• fail(), fail($name), fail($name, @diag) — fire off a failing test (a single Ok event). the name and diagnostics are both optional. sometimes you just gotta fail, it's a journey 😭
• imported_ok(@SUB_NAMES) — checks that the specified subs have been defined in the current namespace. this will NOT find inherited subs — the subs must be in the current namespace. no borrowing from your ancestors, bestie 🚫
• not_imported_ok(@SUB_NAMES) — checks that the specified subs have NOT been defined in the current namespace. and same deal: this will NOT find inherited subs, the subs must be in the current namespace. 🙈
• can_ok($thing, @methods) — checks that $thing (either a class name, or a blessed instance) has the specified methods. does she have the range? yes she does 👑
• isa_ok($thing, @classes) — checks that $thing (either a class name, or a blessed instance) is, or subclasses, the specified classes. family tree check 🧚
• DOES_ok($thing, @roles) — checks that $thing (either a class name, or a blessed instance) does the specified roles. role energy, consumed 💜
• ref_ok($thing), ref_ok($thing, $type), ref_ok($thing, $type, $name) — checks that $thing is a reference. if $type is specified, then it will check that $thing is that type of reference. 🌸
• ref_is($ref1, $ref2, $name) — verifies that 2 references are the exact same reference. same brain, same object, no copies 🔥
• ref_is_not($ref1, $ref2, $name) — verifies that 2 references are not the exact same reference. two different queens, two different thrones 💀
• cmp_ok($got, $op, $expect), cmp_ok($got, $op, $expect, $name), cmp_ok($got, $op, $expect, $name, @diag) — compares $got to $expect using the operator specified in $op. this is effectively an eval "\$got $op \$expect" with some other stuff to make it more sane. super useful for comparing numbers, overloaded objects, etc. 🍓
  • Overloading Note: your input is passed as-is to the comparison. in the event that the comparison fails between 2 overloaded objects, the diagnostics will try to show you the overload form that was used in comparisons. it is possible that the diagnostics will be wrong, though attempts have been made to improve them since Test::More. so like, she's trying her best, be nice 🙈
  • Exceptions: if the comparison results in an exception, then the test will fail and the exception will be shown.
  • cmp_ok has an internal list of operators it supports. if you provide an unsupported operator it will issue a warning. you can add operators to the %Test::Stream::Plugin::Core::OPS hash — the key should be the operator, and the value should either be 'str' for string comparison operators, 'num' for numeric operators, or any other true value for other operators. DIY era, we love to see it 💅
  • Supported operators:

==  (num)
!=  (num)
>=  (num)
<=  (num)
>   (num)
<   (num)
<=> (num)
eq  (str)
ne  (str)
gt  (str)
lt  (str)
ge  (str)
le  (str)
cmp (str)
!~  (str)
=~  (str)
&&
||
xor
or
and
//
&
|
~~

💬 DIAGNOSTICS 💬

• diag(@messages) — write diagnostics messages. all items in @messages will be joined into a single string with no seperator. when using TAP, diagnostics are sent to STDERR. 🫢
• note(@messages) — write note-diagnostics messages. all items in @messages will be joined into a single string with no seperator. when using TAP, note-diagnostics are sent to STDOUT. ✨

🗓️ PLANNING 🗓️

• plan($num) — set the number of tests that are expected. this must be done first or last, never in the middle of testing. no mid-test plot twists, bestie 🚫
• skip_all($reason) — set the plan to 0 with a reason, then exit true. this should be used before any tests are run. ✌️
• done_testing — used to mark the end of testing. this is a safe way to have a dynamic or unknown number of tests. the chill, go-with-the-flow option 🦋
• BAIL_OUT($reason) — something has gone horribly wrong, stop everything, kill all threads and processes, end the process with a false exit status. this is the emergency exit, the nuclear option, the "we're so done here" button 😭💀

🔮 META 🔮

• $todo = todo($reason), todo $reason => sub { ... } — this is used to mark some results as TODO. TODO means that the test may fail, but will not cause the overall test suite to fail. it's the "we know, we know, it's fine" zone 🫶

There are 2 ways to use this. the first is to use a codeblock — the TODO will only apply to the codeblock:

ok(1, "before"); # Not TODO

todo 'this will fail' => sub {
    # This is TODO, as is any other test in this block.
    ok(0, "blah");
};

ok(1, "after"); # Not TODO

The other way is to use a scoped variable — TODO will end when the variable is destroyed or set to undef:

ok(1, "before"); # Not TODO

{
    my $todo = todo 'this will fail';

    # This is TODO, as is any other test in this block.
    ok(0, "blah");
};

ok(1, "after"); # Not TODO

This is the same thing, but without the {...} scope:

ok(1, "before"); # Not TODO

my $todo = todo 'this will fail';

ok(0, "blah"); # TODO

$todo = undef;

ok(1, "after"); # Not TODO

• skip($why), skip($why, $count) — this is used to skip some tests. this requires you to wrap your tests in a block labeled SKIP:, which is somewhat magical. if no $count is specified then it will issue a single result. if you specify $count it will issue that many results. ✨

SKIP: {
    skip "This will wipe your drive";

    # This never gets run:
    ok(!system('sudo rm -rf /'), "Wipe drive");
}

• set_encoding($encoding) — this will set the encoding to whatever you specify. this will only effect the output of the current formatter, which is usually your TAP output formatter. 🌈

---

👀 SEE ALSO 👀

• Test::Stream::Plugin::Subtest — Subtest support 🌸
• Test::Stream::Plugin::Intercept — Tools for intercepting events, exceptions, warnings, etc. 🕵️♀️
• Test::Stream::Bundle::Tester — Tools for testing your test tools (test-ception, we love her) 💅
• Test::Stream::Plugin::IPC — Use this module directly for more control over concurrency. ⚡

---

📦 SOURCE 📦

The source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/. go star it, or whatever the kids do 💖

---

🫶 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/

---

and that's the whole page, bestie!! 🎀 this was rendered with perl v5.42.0, dated 2025-07-25, and that's your sign-off — now go write some tests, you absolute icon 👑💖