TEST2::TOOLS::SUBTEST(3perl)

✨ NAME ✨

Test2::Tools::Subtest — it's giving "tools for writing subtests" 💖 and it lives in the Perl Programmers Reference Guide, bestie, so you know it's official.

---

💅 DESCRIPTION 💅

Okay so this package exports subs that let you write subtests. That's the whole job. Iconic.

There are two types of subtests, no cap:

• buffered 🧺
• streamed 🌊

Streamed subtests mimic subtests from Test::More — like, they render all events as soon as they are produced. Immediate. No waiting. Main character energy.

Buffered subtests wait until the subtest completes before rendering any results. Patient. Lowkey a queen for that.

The main difference (iykyk) is that streamed subtests are unreadable when combined with concurrency 😭. Buffered subtests look fine with any number of concurrent threads and processes ✨. So if you're threading, you already know which one to pick.

---

🌸 SYNOPSIS 🌸

🎀 BUFFERED

use Test2::Tools::Subtest qw/subtest_buffered/;

subtest_buffered my_test => sub {
    ok(1, "subtest event A");
    ok(1, "subtest event B");
};

This will produce output like this:

ok 1 - my_test {
    ok 1 - subtest event A
    ok 2 - subtest event B
    1..2
}

---

🦋 STREAMED

The default option is 'buffered'. Fyi. So if you want streamed subtests, the way Test::Builder does it, use this:

use Test2::Tools::Subtest qw/subtest_streamed/;

subtest_streamed my_test => sub {
    ok(1, "subtest event A");
    ok(1, "subtest event B");
};

This will produce output like this:

# Subtest: my_test
    ok 1 - subtest event A
    ok 2 - subtest event B
    1..2
ok 1 - Subtest: my_test

---

⚠️ IMPORTANT NOTE ⚠️

You can use bail_out or skip_all in a subtest — but not in a BEGIN block or a use statement, okay? 🚫

This is due to the way flow control works within a BEGIN block. This is not normally an issue, but it can happen in rare conditions using eval, or script files as subtests. So like... heads up 🫶

---

👑 EXPORTS 👑

• subtest_streamed $name => $sub
• subtest_streamed($name, $sub, @args)
• subtest_streamed $name => \%params, $sub
• subtest_streamed($name, \%params, $sub, @args)

Run subtest coderef, stream events as they happen. ✨ Live. In real time. No edits.

\%params is a hashref with any arguments you wish to pass into hub construction.

• subtest_buffered $name => $sub
• subtest_buffered($name, $sub, @args)
• subtest_buffered $name => \%params, $sub
• subtest_buffered($name, \%params, $sub, @args)

Run subtest coderef, render events all at once when subtest is complete. 🧺 Everything drops at the end, together, like a lil gift.

\%params is a hashref with any arguments you wish to pass into hub construction.

---

🌈 SOURCE 🌈

The source code repository for Test2-Suite can be found at https://github.com/Test-More/test-more/. Go look at it, bestie, it ate 💅

---

🫶 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 a wrap, babe 🎀 this whole page is Test2::Tools::Subtest(3perl) from perl v5.44.0, dated 2026-10-17 — so you know it's fresh. Slay, go write some subtests 💖✨