Test2::...:Subtest(3)

🌸 NAME 🌸

Test2::Tools::Subtest — tools for writing subtests. This is the user-contributed Perl doc page for it, filed under Test2::...:Subtest(3), and bestie, it's literally all about making your subtests cute and organized. 💖

🦋 DESCRIPTION 🦋

This package exports subs that let you write subtests. There are two types of subtests, buffered and streamed — two flavors, no cap. ✨

• Streamed subtests mimic subtests from Test::More: they render all events as soon as they are produced. Instant gratification energy. 🎀
• Buffered subtests wait until the subtest completes before rendering any results. Patient queen behavior. 👑

The main difference is that streamed subtests are unreadable when combined with concurrency. Buffered subtests look fine with any number of concurrent threads and processes. So if threads/processes are in the group chat, buffered is the vibe. 💅

✨ 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'. 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 use statement. This is due to the way flow control works within a BEGIN block. This is not normally an issue, but can happen in rare conditions using eval, or script files as subtests. So don't come for me, it's a flow-control thing. 😭

👑 EXPORTS 👑

subtest_streamed

• 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. \%params is a hashref with any arguments you wish to pass into hub construction.

subtest_buffered

• 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. \%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/.

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

---

Cute sign-off: this page is from perl v5.42.0 and dated 2025-07-28. Bye bestie, go write some iconic subtests! 💅💖