TEST2::TOOLS::BASIC(3pm)

💅 NAME 💅

Test2::Tools::Basic — bestie, it's the Test2 glow-up of the basic testing tools, living its best life in the Perl Programmers Reference Guide. 🎀

---

✨ DESCRIPTION ✨

Okay so picture this: the classic basic tools from Test::More, but rebuilt on Test2, and honestly? It ate. 🔥 Not every Test::More tool made the cut — only the basic/simple ones, because we keep it cute and uncluttered. A few tools got a lil makeover too so the diagnostics hit way harder. Ngl, the diagnostics are giving main character energy now. 👑

---

🦋 SYNOPSIS 🦋

use Test2::Tools::Basic;

ok($x, "simple test");

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

diag "This is a diagnostics message on STDERR";
note "This is a diagnostics message on STDOUT";

{
    my $todo = todo "Reason for todo";
    ok(0, "this test is todo");
}

ok(1, "this test is not todo");

todo "reason" => sub {
    ok(0, "this test is todo");
};

ok(1, "this test is not todo");

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

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

done_testing;

---

🌸 EXPORTS 🌸

Every single sub is exported by default. No asking, no negotiating — they just show up for you. 🫶

🎀 PLANNING 🎀

• plan($num)
• plan('tests' => $num)
• plan('skip_all' => $reason)

Set the number of tests that are expected. Okay and this part is important, bestie: this has to be done first or last, never ever in the middle of testing. Not mid-test. Nope. 🙈

For legacy compatibility you can also put 'tests' as the first argument before the number — a lil throwback moment. And you can use this to skip all with the 'skip_all' prefix, followed by a reason for skipping. 💖

• skip_all($reason)

Sets the plan to 0 with a reason, then exits true. Do this before any tests are run, mkay? ⭐

• done_testing

Marks the end of testing. This is the safe way to have a dynamic or unknown number of tests — very "we'll see how it goes" of you, and honestly iconic. 💅

• bail_out($reason)

Invoked when something has gone horribly wrong: stop everything, kill all threads and processes, and end the process with a false exit status. 💀 This is the nuclear option, fr fr — the process does not survive.

🧚 ASSERTIONS 🧚

• ok($bool)
• ok($bool, $name)
• ok($bool, $name, @diag)

Simple assertion, no cap. If $bool is true, the test passes; if it's false, the test fails. The test name is optional. And here's the tea: 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 just get ignored. 🦋

• pass()
• pass($name)

Fires off a passing test (a single Ok event). The name is optional. Little victory lap. 🎉

• fail()
• fail($name)
• fail($name, @diag)

Fires off a failing test (a single Ok event). The name and diagnostics are both optional. It's giving "it's fine, everything's fine." 😭

🌈 DIAGNOSTICS 🌈

• diag(@messages)

Writes diagnostics messages. All items in @messages will be joined into a single string with no separator. When using TAP, diagnostics get sent to STDERR.

Returns false, so as to preserve failure. Respect the commitment to the bit. 🙈

• note(@messages)

Writes note-diagnostics messages. All items in @messages get joined into a single string with no separator. When using TAP, notes are sent to STDOUT. Very "just leaving a note in the group chat" of it. 💌

👑 META 👑

• $todo = todo($reason)
• todo $reason => sub { ... }

This marks some results as TODO. TODO means the test may fail but won't cause the overall test suite to fail. Basically: "not me, but also not a problem." 😌

There are two ways to use this. The first is a codeblock, where the TODO only applies 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 a scoped variable. TODO ends 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

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)

Skips some tests. This requires you to wrap your tests in a block labeled SKIP:. It's somewhat magical ✨ — like, actual wizard behavior, bestie. If no $count is specified it issues a single result. If you specify $count it'll issue that many results. 🎀

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

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

Yeah so, that sudo rm -rf / in there? That's the whole joke — it's the "this will wipe your drive" test that never gets run because it's skipped. Please do not actually run it. 😭💀

---

💜 SOURCE 💜

The source code repository for Test2-Suite can be found at https://github.com/Test-More/test-more/. Go give it a star, it deserves it. ⭐

---

🍓 MAINTAINERS 🍓

Chad Granum <exodist@cpan.org>

---

🌸 AUTHORS 🌸

Chad Granum <exodist@cpan.org>

---

🦋 COPYRIGHT 🦋

Copyright Chad Granum <exodist@cpan.org>.

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! 🫶 Run wild, write tests, don't rm -rf /. Signing off from perl v5.42.3, dated 2026-11-03 — mwah 💋✨