Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test2::Workflow.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::Workflow 3pm"
61 .TH Test2::Workflow 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::Workflow \- A test workflow is a way of structuring tests using
68 composable units.
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 A test workflow is a way of structuring tests using composable units. A well
72 known example of a test workflow is RSPEC <http://rspec.info/>. RSPEC is
73 implemented using Test2::Workflow in Test2::Tools::Spec along with several
74 extensions.
75 .SH "IMPORTANT CONCEPTS"
76 .IX Header "IMPORTANT CONCEPTS"
77 .SS BUILD
78 .IX Subsection "BUILD"
79 Test2::Workflow::Build
80 .PP
81 A Build is used to compose tasks. Usually a build object is pushed to the stack
82 before running code that adds tasks to the build. Once the build sub is
83 complete the build is popped and returned. Usually a build is converted into a
84 root task or task group.
85 .SS RUNNER
86 .IX Subsection "RUNNER"
87 Test2::Workflow::Runner
88 .PP
89 A runner takes the composed tasks and executes them in the proper order.
90 .SS TASK
91 .IX Subsection "TASK"
92 Test2::Workflow::Task
93 .PP
94 A task is a unit of work to accomplish. There are 2 main types of task.
95 .PP
96 \fIACTION\fR
97 .IX Subsection "ACTION"
98 .PP
99 An action is the most simple unit used in composition. An action is essentially
100 a name and a codeblock to run.
101 .PP
102 \fIGROUP\fR
103 .IX Subsection "GROUP"
104 .PP
105 A group is a task that is composed of other tasks.
106 .SH EXPORTS
107 .IX Header "EXPORTS"
108 All exports are optional, you must request the ones you want.
109 .ie n .IP "$parsed = parse_args(args => \e@args)" 4
110 .el .IP "\f(CW$parsed\fR = parse_args(args => \e@args)" 4
111 .IX Item "$parsed = parse_args(args => @args)"
112 .PD 0
113 .ie n .IP "$parsed = parse_args(args => \e@args, level => $L)" 4
114 .el .IP "\f(CW$parsed\fR = parse_args(args => \e@args, level => \f(CW$L\fR)" 4
115 .IX Item "$parsed = parse_args(args => @args, level => $L)"
116 .ie n .IP "$parsed = parse_args(args => \e@args, caller => [caller($L)])" 4
117 .el .IP "\f(CW$parsed\fR = parse_args(args => \e@args, caller => [caller($L)])" 4
118 .IX Item "$parsed = parse_args(args => @args, caller => [caller($L)])"
119 .PD
120 This will parse a "typical" task builders arguments. The \f(CW@args\fR array MUST
121 contain a name (plain scalar containing text) and also a single CODE reference.
122 The \f(CW@args\fR array MAY also contain any quantity of line numbers or hashrefs.
123 The resulting data structure will be a single hashref with all the provided
124 hashrefs squashed together, and the \*(Aqname\*(Aq, \*(Aqcode\*(Aq, \*(Aqlines\*(Aq and \*(Aqframe\*(Aq keys
125 set from other arguments.
126 .Sp
127 .Vb 3
128 \& {
129 \& # All hashrefs from @args get squashed together:
130 \& %squashed_input_hashref_data,
131 \&
132 \& # @args must have exactly 1 plaintext scalar that is not a number, it
133 \& # is considered the name:
134 \& name => \*(Aqname from input args\*(Aq
135 \&
136 \& # Integer values are treated as line numbers
137 \& lines => [ 35, 44 ],
138 \&
139 \& # Exactly 1 coderef must be provided in @args:
140 \& code => \e&some_code,
141 \&
142 \& # \*(Aqframe\*(Aq contains the \*(Aqcaller\*(Aq data. This may be passed in directly,
143 \& # obtained from the \*(Aqlevel\*(Aq parameter, or automatically deduced.
144 \& frame => [\*(AqA::Package\*(Aq, \*(Aqa_file.pm\*(Aq, 42, ...],
145 \& }
146 .Ve
147 .ie n .IP "$build = init_root($pkg, %args)" 4
148 .el .IP "\f(CW$build\fR = init_root($pkg, \f(CW%args\fR)" 4
149 .IX Item "$build = init_root($pkg, %args)"
150 This will initialize (or return the existing) a build for the specified
151 package. \f(CW%args\fR get passed into the Test2::Workflow::Build constructor.
152 This uses the following defaults (which can be overridden using \f(CW%args\fR):
153 .Sp
154 .Vb 5
155 \& name => $pkg,
156 \& flat => 1,
157 \& iso => 0,
158 \& async => 0,
159 \& is_root => 1,
160 .Ve
161 .Sp
162 Note that \f(CW%args\fR is completely ignored if the package build has already been
163 initialized.
164 .ie n .IP "$build = root_build($pkg)" 4
165 .el .IP "\f(CW$build\fR = root_build($pkg)" 4
166 .IX Item "$build = root_build($pkg)"
167 This will return the root build for the specified package.
168 .ie n .IP "$build = \fBcurrent_build()\fR" 4
169 .el .IP "\f(CW$build\fR = \fBcurrent_build()\fR" 4
170 .IX Item "$build = current_build()"
171 This will return the build currently at the top of the build stack (or undef).
172 .ie n .IP "$build = build($name, \e%params, sub { ... })" 4
173 .el .IP "\f(CW$build\fR = build($name, \e%params, sub { ... })" 4
174 .IX Item "$build = build($name, %params, sub { ... })"
175 This will push a new build object onto the build stash then run the provided
176 codeblock. Once the codeblock has finished running the build will be popped off
177 the stack and returned.
178 .Sp
179 See \f(CWparse_args()\fR for details about argument processing.
180 .SH "SEE ALSO"
181 .IX Header "SEE ALSO"
182 .IP Test2::Tools::Spec 4
183 .IX Item "Test2::Tools::Spec"
184 Test2::Tools::Spec is an implementation of RSPEC using this library.
185 .SH SOURCE
186 .IX Header "SOURCE"
187 The source code repository for Test2\-Workflow can be found at
188 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
189 .SH MAINTAINERS
190 .IX Header "MAINTAINERS"
191 .IP "Chad Granum <[email protected]>" 4
192 .IX Item "Chad Granum <[email protected]>"
193 .SH AUTHORS
194 .IX Header "AUTHORS"
195 .IP "Chad Granum <[email protected]>" 4
196 .IX Item "Chad Granum <[email protected]>"
197 .SH COPYRIGHT
198 .IX Header "COPYRIGHT"
199 Copyright Chad Granum <[email protected]>.
200 .PP
201 This program is free software; you can redistribute it and/or
202 modify it under the same terms as Perl itself.
203 .PP
204 See \fIhttp://dev.perl.org/licenses/\fR