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/