.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Test2::Manual::Tooling::Subtest 3pm"
.TH Test2::Manual::Tooling::Subtest 3pm "2019-05-06" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test2::Manual::Tooling::Subtest \- How to implement a tool that makes use of
subtests.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Subtests are a nice way of making related events visually, and architecturally
distinct.
.SH "WHICH TYPE OF SUBTEST DO I NEED?"
.IX Header "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 \f(CW\*(C`subtest()\*(C'\fR function itself. The second type is subtest
that do not have any user supplied coderefs.
.PP
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.
.PP
In either case, you will still need use the same \s-1API\s0 function:
\&\f(CW\*(C`Test2::API::run_subtest\*(C'\fR.
.SS "\s-1SUBTEST WITH USER SUPPLIED CODEREF\s0"
.IX Subsection "SUBTEST WITH USER SUPPLIED CODEREF"
This example will emulate the \f(CW\*(C`subtest\*(C'\fR function.
.PP
.Vb 1
\&    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;
\&    }
.Ve
.PP
This looks incredibly simple... and it is. \f(CW\*(C`run_subtest()\*(C'\fR 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 \fIlook\fR
like you used the context.
.PP
\&\f(CW\*(C`run_subtest()\*(C'\fR can take additional arguments:
.PP
.Vb 1
\&    run_subtest($name, $code, \e%params, @args);
.Ve
.ie n .IP "@args" 4
.el .IP "\f(CW@args\fR" 4
.IX Item "@args"
This allows you to pass arguments into the codeblock that gets run.
.IP "\e%params" 4
.IX Item "%params"
This is a hashref of parameters. Currently there are 3 possible parameters:
.RS 4
.ie n .IP "buffered => $bool" 4
.el .IP "buffered => \f(CW$bool\fR" 4
.IX Item "buffered => $bool"
This will turn the subtest into the new style buffered subtest. This type of
subtest is recommended, but not default.
.ie n .IP "inherit_trace => $bool" 4
.el .IP "inherit_trace => \f(CW$bool\fR" 4
.IX Item "inherit_trace => $bool"
This is used for tool-side coderefs.
.ie n .IP "no_fork => $bool" 4
.el .IP "no_fork => \f(CW$bool\fR" 4
.IX Item "no_fork => $bool"
react to forking/threading inside the subtest itself. In general you are
unlikely to need/want this parameter.
.RE
.RS 4
.RE
.SS "\s-1SUBTEST WITH\s0 TOOL-SIDE \s-1CODEREF\s0"
.IX Subsection "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.
.PP
.Vb 1
\&    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, \*(Aqfoo\*(Aq, "got foo");
\&            is($obj\->bar, \*(Aqbar\*(Aq, "got bar");
\&        };
\&
\&        my $bool = run_subtest($class, $code, {buffered => 1, inherit_trace => 1});
\&
\&        $ctx\->release;
\&
\&        return $bool;
\&    }
.Ve
.PP
The \f(CW\*(C`run_subtest()\*(C'\fR 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
\&\f(CW\*(C`inherit_trace => 1\*(C'\fR parameter. The \f(CW\*(C`buffered => 1\*(C'\fR parameter is
optional, but recommended.
.PP
The \f(CW\*(C`inherit_trace\*(C'\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test2::Manual \- Primary index of the manual.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Test2\-Manual can be found at
\&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH "AUTHORS"
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2018 Chad Granum <exodist@cpan.org>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See \fIhttp://dev.perl.org/licenses/\fR