Debian Codegraph @

upstream/debian-unstable/man3/Test2::Manual::Tooling::Subtest.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Test2::Manual::Tooling::Subtest 3perl"
58 .TH Test2::Manual::Tooling::Subtest 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test2::Manual::Tooling::Subtest \- How to implement a tool that makes use of
65 subtests.
66 .SH DESCRIPTION
67 .IX Header "DESCRIPTION"
68 Subtests are a nice way of making related events visually, and architecturally
69 distinct.
70 .SH "WHICH TYPE OF SUBTEST DO I NEED?"
71 .IX Header "WHICH TYPE OF SUBTEST DO I NEED?"
72 There are 2 types of subtest. The first type is subtests with user-supplied
73 coderefs, such as the \f(CWsubtest()\fR function itself. The second type is subtest
74 that do not have any user supplied coderefs.
75 .PP
76 So which type do you need? The answer to that is simple, if you are going to
77 let the user define the subtest with their own codeblock, you have the first
78 type, otherwise you have the second.
79 .PP
80 In either case, you will still need use the same API function:
81 \&\f(CW\*(C`Test2::API::run_subtest\*(C'\fR.
82 .SS "SUBTEST WITH USER SUPPLIED CODEREF"
83 .IX Subsection "SUBTEST WITH USER SUPPLIED CODEREF"
84 This example will emulate the \f(CW\*(C`subtest\*(C'\fR function.
85 .PP
86 .Vb 1
87 \& use Test2::API qw/context run_subtest/;
88 \&
89 \& sub my_subtest {
90 \& my ($name, $code) = @_;
91 \&
92 \& # Like any other tool, you need to acquire a context, if you do not then
93 \& # things will not report the correct file and line number.
94 \& my $ctx = context();
95 \&
96 \& my $bool = run_subtest($name, $code);
97 \&
98 \& $ctx\->release;
99 \&
100 \& return $bool;
101 \& }
102 .Ve
103 .PP
104 This looks incredibly simple... and it is. \f(CWrun_subtest()\fR does all the hard
105 work for you. This will issue an Test2::Event::Subtest event with the
106 results of the subtest. The subtest event itself will report to the proper file
107 and line number due to the context you acquired (even though it does not \fIlook\fR
108 like you used the context.
109 .PP
110 \&\f(CWrun_subtest()\fR can take additional arguments:
111 .PP
112 .Vb 1
113 \& run_subtest($name, $code, \e%params, @args);
114 .Ve
115 .ie n .IP @args 4
116 .el .IP \f(CW@args\fR 4
117 .IX Item "@args"
118 This allows you to pass arguments into the codeblock that gets run.
119 .IP \e%params 4
120 .IX Item "%params"
121 This is a hashref of parameters. Currently there are 3 possible parameters:
122 .RS 4
123 .ie n .IP "buffered => $bool" 4
124 .el .IP "buffered => \f(CW$bool\fR" 4
125 .IX Item "buffered => $bool"
126 This will turn the subtest into the new style buffered subtest. This type of
127 subtest is recommended, but not default.
128 .ie n .IP "inherit_trace => $bool" 4
129 .el .IP "inherit_trace => \f(CW$bool\fR" 4
130 .IX Item "inherit_trace => $bool"
131 This is used for tool-side coderefs.
132 .ie n .IP "no_fork => $bool" 4
133 .el .IP "no_fork => \f(CW$bool\fR" 4
134 .IX Item "no_fork => $bool"
135 react to forking/threading inside the subtest itself. In general you are
136 unlikely to need/want this parameter.
137 .RE
138 .RS 4
139 .RE
140 .SS "SUBTEST WITH TOOL-SIDE CODEREF"
141 .IX Subsection "SUBTEST WITH TOOL-SIDE CODEREF"
142 This is particularly useful if you want to turn a tool that wraps other tools
143 into a subtest. For this we will be using the tool we created in
144 Test2::Manual::Tooling::Nesting.
145 .PP
146 .Vb 1
147 \& use Test2::API qw/context run_subtest/;
148 \&
149 \& sub check_class {
150 \& my $class = shift;
151 \&
152 \& my $ctx = context();
153 \&
154 \& my $code = sub {
155 \& my $obj = $class\->new;
156 \& is($obj\->foo, \*(Aqfoo\*(Aq, "got foo");
157 \& is($obj\->bar, \*(Aqbar\*(Aq, "got bar");
158 \& };
159 \&
160 \& my $bool = run_subtest($class, $code, {buffered => 1, inherit_trace => 1});
161 \&
162 \& $ctx\->release;
163 \&
164 \& return $bool;
165 \& }
166 .Ve
167 .PP
168 The \f(CWrun_subtest()\fR function does all the heavy lifting for us. All we need
169 to do is give the function a name, a coderef to run, and the
170 \&\f(CW\*(C`inherit_trace => 1\*(C'\fR parameter. The \f(CW\*(C`buffered => 1\*(C'\fR parameter is
171 optional, but recommended.
172 .PP
173 The \f(CW\*(C`inherit_trace\*(C'\fR parameter tells the subtest tool that the contexts acquired
174 inside the nested tools should use the same trace as the subtest itself. For
175 user-supplied codeblocks you do not use inherit_trace because you want errors
176 to report to the user-supplied file+line.
177 .SH "SEE ALSO"
178 .IX Header "SEE ALSO"
179 Test2::Manual \- Primary index of the manual.
180 .SH SOURCE
181 .IX Header "SOURCE"
182 The source code repository for Test2\-Manual can be found at
183 \&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
184 .SH MAINTAINERS
185 .IX Header "MAINTAINERS"
186 .IP "Chad Granum <[email protected]>" 4
187 .IX Item "Chad Granum <[email protected]>"
188 .SH AUTHORS
189 .IX Header "AUTHORS"
190 .PD 0
191 .IP "Chad Granum <[email protected]>" 4
192 .IX Item "Chad Granum <[email protected]>"
193 .PD
194 .SH COPYRIGHT
195 .IX Header "COPYRIGHT"
196 Copyright 2018 Chad Granum <[email protected]>.
197 .PP
198 This program is free software; you can redistribute it and/or
199 modify it under the same terms as Perl itself.
200 .PP
201 See \fIhttp://dev.perl.org/licenses/\fR