Debian Codegraph @

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