TEST2::MANUAL::TOOLING::SUBTEST(3perl)

🎀 Test2::Manual::Tooling::Subtest 💅

okay bestie, welcome to Test2::Manual::Tooling::Subtest — this one's all about how to build a tool that makes use of subtests. 🫶

---

✨ DESCRIPTION ✨

Subtests are that girl. They're a nice way of making related events look visually distinct, and architecturally distinct too. Two kinds of separation for the price of one, we love. 💖

---

🌸 WHICH TYPE OF SUBTEST DO I NEED? 🌸

so there are 2 types of subtest, and you gotta know which one you're dealing with:

1. subtests with user-supplied coderefs — like the subtest() function itself, where the user hands you their own block of code
2. subtests that do not have any user supplied coderefs

so which one do you need? bestie it's actually so simple: if you're gonna let the user define the subtest with their own codeblock, you've got the first type. otherwise? second type. that's it. 💅

but either way — either way — you still need the same API function:

Test2::API::run_subtest

periodt. 🎀

---

🦋 SUBTEST WITH USER SUPPLIED CODEREF 🦋

this example is gonna emulate the subtest function. watch:

use Test2::API qw/context run_subtest/;

sub my_subtest {
    my ($name, $code) = @_;

    # Like any other tool, you need to acquire a context, if you do not then
    # things will not report the correct file and line number.
    my $ctx = context();

    my $bool = run_subtest($name, $code);

    $ctx->release;

    return $bool;
}

ngl this looks incredibly simple... and it is, because run_subtest() does all the hard work for you. 😭 it'll issue a Test2::Event::Subtest event carrying the results of the subtest. and the subtest event itself will report to the proper file and line number thanks to the context you acquired — even though it doesn't look like you used the context. sneaky iconic behavior. 👑

and plot twist: run_subtest() can take extra arguments too:

run_subtest($name, $code, \%params, @args);

⭐ @args

this lets you pass arguments into the codeblock that gets run. yes bestie, the codeblock gets fed. 🍓

⭐ \%params

this is a hashref of parameters. currently there are 3 possible parameters:

• buffered => $bool — this turns the subtest into the new style buffered subtest. this type of subtest is recommended, but it is not default. so like, do the recommended thing, but know nobody's forcing you. 🙈
• inherit_trace => $bool — this one is used for tool-side coderefs.
• no_fork => $bool — react to forking/threading inside the subtest itself. in general you are unlikely to need or want this parameter, it's giving niche. 💀

---

🌈 SUBTEST WITH TOOL-SIDE CODEREF 🌈

this one is particularly useful if you want to turn a tool that wraps other tools into a subtest. for this we're using the tool we created in Test2::Manual::Tooling::Nesting. full circle moment fr fr.

use Test2::API qw/context run_subtest/;

sub check_class {
    my $class = shift;

    my $ctx = context();

    my $code = sub {
        my $obj = $class->new;
        is($obj->foo, 'foo', "got foo");
        is($obj->bar, 'bar', "got bar");
    };

    my $bool = run_subtest($class, $code, {buffered => 1, inherit_trace => 1});

    $ctx->release;

    return $bool;
}

the run_subtest() function does all the heavy lifting for us — main character energy, honestly. all we need to do is hand it a name, a coderef to run, and the inherit_trace => 1 parameter. the buffered => 1 parameter is optional, but recommended. 💅

so what does inherit_trace actually do? it tells the subtest tool that the contexts acquired inside the nested tools should use the same trace as the subtest itself. that's the whole vibe. 🧚

and here's the important bit — for user-supplied codeblocks you do not use inherit_trace, because you want errors to report to the user-supplied file+line. iykyk. don't mix these up bestie, that's the whole point. 😭

---

👑 SEE ALSO 👑

• Test2::Manual — Primary index of the manual. the mothership, the main hub, start here. 💜

---

💖 SOURCE 💖

the source code repository for Test2-Manual can be found at https://github.com/Test-More/test-more/. go peek, it's cute. ✨

---

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

---

okay that's the whole page bestie, you ate. 🫶

and a lil sign-off for the record books: this was perl v5.44.0, dated 2026-10-17, filed under Test2:...Subtest(3perl). slay, go write that tool. 💖🔥👑