TEST2::TOOLS::BASIC(3perl)

✨ Test2::Tools::Basic ✨

okay bestie, welcome to Test2:...::Basic — wait, that's the rendered name in your man page (Test2::Tools::Basic(3perl), the section-3 Perl page, iykyk). This is the Test2 glow-up of the basic testing tools, and honestly? she ate. 💅

---

🌸 NAME 🌸

Test2::Tools::Basic — the Test2 implementation of the basic testing tools. she's simple, she's iconic, she's your bestie for writing tests.

---

🦋 DESCRIPTION 🦋

So here's the vibe: this is a Test2-based redo of the more basic tools that were originally handed down to us by Test::More. 👑

Not all Test::More tools live here — only the basic/simple ones, no cap. Some tools got a lil' glow-up with better diagnostics capabilities. ✨

---

💖 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 🎀

All subs are exported by default. literally all of them, no import gymnastics required. periodt.

---

🌈 PLANNING 🌈

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

Sets the number of tests you're expecting. ⚠️ This has to go first or last, never mid-testing — that's the rule, bestie, don't fight it.

For legacy compatibility you can slip 'tests' in as the first argument before the number. You can also use this to skip everything with the 'skip_all' prefix, followed by a reason for skipping. slay.

• skip_all($reason)

Sets the plan to 0 with a reason, then exits true. Use this before any tests run, okay? 🌸

• done_testing

Marks the end of testing. This is the safe way to handle a dynamic or unknown number of tests. main character move fr.

• bail_out($reason)

Called when something has gone horribly wrong 💀 — stop everything, kill all threads and processes, end the process with a false exit status. it's giving emergency brake.

---

⭐ ASSERTIONS ⭐

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

Simple assertion. If $bool is true the test passes ✅, if it's false the test fails ❌. The test name is optional, and every argument after the name gets added as a diagnostics message if and only if the test fails. If the test passes, all those diagnostics args get ignored. rude but fair. 🙈

• pass()
• pass($name)

Fires off a passing test (a single Ok event). The name is optional 💚

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

Fires off a failing test (a single Ok event). The name and diagnostics are optional. 😭

---

🔥 DIAGNOSTICS 🔥

• diag(@messages)

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

Returns false, so as to preserve failure. lowkey iconic.

• note(@messages)

Writes note-diagnostics messages. All items in @messages get joined into a single string with no separator. When using TAP, notes go to STDOUT. 🫶

---

🧚 META 🧚

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

Marks some results as TODO. TODO means the test may fail, but it will not cause the overall test suite to fail. the whole point is: she's allowed to flop, and the suite still passes. 😌

There are two ways to use this. The first is with a codeblock, and the TODO only applies to that 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 gets 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, just 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:". This is somewhat magical — yes, actual magic, we said it. If no $count is specified it issues a single result. If you specify $count it issues that many results. ✨

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

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

heads up bestie: that sudo rm -rf / in the example is there to show you code that never runs because it's skipped. do not be out here running it for real. 💀

---

🍓 SOURCE 🍓

The source code repository for Test2-Suite can be found at https://github.com/Test-More/test-more/. go star it, it's free. ⭐

---

👑 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 🫶 this was perl v5.44.0, dated 2026-10-17, from the Test2:...::Basic(3perl) page. go write some tests, you're gonna slay 💅✨