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:

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.