Test2:...Subtest(3perl) Perl Programmers Reference GuideTest2:...Subtest(3perl)
NAME
Test2::Manual::Tooling::Subtest - How to implement a tool that makes use
of subtests.
DESCRIPTION
Subtests are a nice way of making related events visually, and
architecturally distinct.
WHICH TYPE OF SUBTEST DO I NEED?
There are 2 types of subtest. The first type is subtests with user-
supplied coderefs, such as the subtest() function itself. The second
type is subtest that do not have any user supplied coderefs.
So which type do you need? The answer to that is simple, if you are
going to let the user define the subtest with their own codeblock, you
have the first type, otherwise you have the second.
In either case, you will still need use the same API function:
"Test2::API::run_subtest".
SUBTEST WITH USER SUPPLIED CODEREF
This example will emulate the "subtest" function.
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;
}
This looks incredibly simple... and it is. run_subtest() does all the
hard work for you. This will issue an Test2::Event::Subtest event with
the results of the subtest. The subtest event itself will report to the
proper file and line number due to the context you acquired (even though
it does not look like you used the context.
run_subtest() can take additional arguments:
run_subtest($name, $code, \%params, @args);
@args
This allows you to pass arguments into the codeblock that gets run.
\%params
This is a hashref of parameters. Currently there are 3 possible
parameters:
buffered => $bool
This will turn the subtest into the new style buffered subtest.
This type of subtest is recommended, but not default.
inherit_trace => $bool
This is used for tool-side coderefs.
no_fork => $bool
react to forking/threading inside the subtest itself. In general
you are unlikely to need/want this parameter.
SUBTEST WITH TOOL-SIDE CODEREF
This is particularly useful if you want to turn a tool that wraps other
tools into a subtest. For this we will be using the tool we created in
Test2::Manual::Tooling::Nesting.
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. All we
need to do is give the function a name, a coderef to run, and the
"inherit_trace => 1" parameter. The "buffered => 1" parameter is
optional, but recommended.
The "inherit_trace" parameter tells the subtest tool that the contexts
acquired inside the nested tools should use the same trace as the
subtest itself. For user-supplied codeblocks you do not use
inherit_trace because you want errors to report to the user-supplied
file+line.
SEE ALSO
Test2::Manual - Primary index of the manual.
SOURCE
The source code repository for Test2-Manual can be found at
https://github.com/Test-More/Test2-Suite/.
MAINTAINERS
Chad Granum <exodist@cpan.org>
AUTHORS
Chad Granum <exodist@cpan.org>
COPYRIGHT
Copyright 2018 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/
perl v5.40.1 2026-08-30 Test2:...Subtest(3perl)
Generated by dwww version 1.16 on Sat Oct 3 06:00:47 CEST 2026.