Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test2::Manual::Tooling::Subtest.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Manual::Tooling::Subtest 3pm"
61 .TH Test2::Manual::Tooling::Subtest 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Manual::Tooling::Subtest \- How to implement a tool that makes use of
68 subtests.
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 Subtests are a nice way of making related events visually, and architecturally
72 distinct.
73 .SH "WHICH TYPE OF SUBTEST DO I NEED?"
74 .IX Header "WHICH TYPE OF SUBTEST DO I NEED?"
75 There are 2 types of subtest. The first type is subtests with user\-supplied
76 coderefs, such as the \f(CWsubtest()\fR function itself. The second type is subtest
77 that do not have any user supplied coderefs.
78 .PP
79 So which type do you need? The answer to that is simple, if you are going to
80 let the user define the subtest with their own codeblock, you have the first
81 type, otherwise you have the second.
82 .PP
83 In either case, you will still need use the same API function:
84 \&\f(CW\*(C`Test2::API::run_subtest\*(C'\fR.
85 .SS "SUBTEST WITH USER SUPPLIED CODEREF"
86 .IX Subsection "SUBTEST WITH USER SUPPLIED CODEREF"
87 This example will emulate the \f(CW\*(C`subtest\*(C'\fR function.
88 .PP
89 .Vb 1
90 \& use Test2::API qw/context run_subtest/;
91 \&
92 \& sub my_subtest {
93 \& my ($name, $code) = @_;
94 \&
95 \& # Like any other tool, you need to acquire a context, if you do not then
96 \& # things will not report the correct file and line number.
97 \& my $ctx = context();
98 \&
99 \& my $bool = run_subtest($name, $code);
100 \&
101 \& $ctx\->release;
102 \&
103 \& return $bool;
104 \& }
105 .Ve
106 .PP
107 This looks incredibly simple... and it is. \f(CWrun_subtest()\fR does all the hard
108 work for you. This will issue an Test2::Event::Subtest event with the
109 results of the subtest. The subtest event itself will report to the proper file
110 and line number due to the context you acquired (even though it does not \fIlook\fR
111 like you used the context.
112 .PP
113 \&\f(CWrun_subtest()\fR can take additional arguments:
114 .PP
115 .Vb 1
116 \& run_subtest($name, $code, \e%params, @args);
117 .Ve
118 .ie n .IP @args 4
119 .el .IP \f(CW@args\fR 4
120 .IX Item "@args"
121 This allows you to pass arguments into the codeblock that gets run.
122 .IP \e%params 4
123 .IX Item "%params"
124 This is a hashref of parameters. Currently there are 3 possible parameters:
125 .RS 4
126 .ie n .IP "buffered => $bool" 4
127 .el .IP "buffered => \f(CW$bool\fR" 4
128 .IX Item "buffered => $bool"
129 This will turn the subtest into the new style buffered subtest. This type of
130 subtest is recommended, but not default.
131 .ie n .IP "inherit_trace => $bool" 4
132 .el .IP "inherit_trace => \f(CW$bool\fR" 4
133 .IX Item "inherit_trace => $bool"
134 This is used for tool\-side coderefs.
135 .ie n .IP "no_fork => $bool" 4
136 .el .IP "no_fork => \f(CW$bool\fR" 4
137 .IX Item "no_fork => $bool"
138 react to forking/threading inside the subtest itself. In general you are
139 unlikely to need/want this parameter.
140 .RE
141 .RS 4
142 .RE
143 .SS "SUBTEST WITH TOOL\-SIDE CODEREF"
144 .IX Subsection "SUBTEST WITH TOOL-SIDE CODEREF"
145 This is particularly useful if you want to turn a tool that wraps other tools
146 into a subtest. For this we will be using the tool we created in
147 Test2::Manual::Tooling::Nesting.
148 .PP
149 .Vb 1
150 \& use Test2::API qw/context run_subtest/;
151 \&
152 \& sub check_class {
153 \& my $class = shift;
154 \&
155 \& my $ctx = context();
156 \&
157 \& my $code = sub {
158 \& my $obj = $class\->new;
159 \& is($obj\->foo, \*(Aqfoo\*(Aq, "got foo");
160 \& is($obj\->bar, \*(Aqbar\*(Aq, "got bar");
161 \& };
162 \&
163 \& my $bool = run_subtest($class, $code, {buffered => 1, inherit_trace => 1});
164 \&
165 \& $ctx\->release;
166 \&
167 \& return $bool;
168 \& }
169 .Ve
170 .PP
171 The \f(CWrun_subtest()\fR function does all the heavy lifting for us. All we need
172 to do is give the function a name, a coderef to run, and the
173 \&\f(CW\*(C`inherit_trace => 1\*(C'\fR parameter. The \f(CW\*(C`buffered => 1\*(C'\fR parameter is
174 optional, but recommended.
175 .PP
176 The \f(CW\*(C`inherit_trace\*(C'\fR parameter tells the subtest tool that the contexts acquired
177 inside the nested tools should use the same trace as the subtest itself. For
178 user\-supplied codeblocks you do not use inherit_trace because you want errors
179 to report to the user\-supplied file+line.
180 .SH "SEE ALSO"
181 .IX Header "SEE ALSO"
182 Test2::Manual \- Primary index of the manual.
183 .SH SOURCE
184 .IX Header "SOURCE"
185 The source code repository for Test2\-Manual can be found at
186 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
187 .SH MAINTAINERS
188 .IX Header "MAINTAINERS"
189 .IP "Chad Granum <[email protected]>" 4
190 .IX Item "Chad Granum <[email protected]>"
191 .SH AUTHORS
192 .IX Header "AUTHORS"
193 .IP "Chad Granum <[email protected]>" 4
194 .IX Item "Chad Granum <[email protected]>"
195 .SH COPYRIGHT
196 .IX Header "COPYRIGHT"
197 Copyright Chad Granum <[email protected]>.
198 .PP
199 This program is free software; you can redistribute it and/or
200 modify it under the same terms as Perl itself.
201 .PP
202 See \fIhttp://dev.perl.org/licenses/\fR