.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test2::Workflow 3"
.TH Test2::Workflow 3 2024-05-12 "perl v5.38.2" "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::Workflow \- A test workflow is a way of structuring tests using
composable units.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
A test workflow is a way of structuring tests using composable units. A well
known example of a test workflow is RSPEC <http://rspec.info/>. RSPEC is
implemented using Test2::Workflow in Test2::Tools::Spec along with several
extensions.
.SH "IMPORTANT CONCEPTS"
.IX Header "IMPORTANT CONCEPTS"
.SS BUILD
.IX Subsection "BUILD"
Test2::Workflow::Build
.PP
A Build is used to compose tasks. Usually a build object is pushed to the stack
before running code that adds tasks to the build. Once the build sub is
complete the build is popped and returned. Usually a build is converted into a
root task or task group.
.SS RUNNER
.IX Subsection "RUNNER"
Test2::Workflow::Runner
.PP
A runner takes the composed tasks and executes them in the proper order.
.SS TASK
.IX Subsection "TASK"
Test2::Workflow::Task
.PP
A task is a unit of work to accomplish. There are 2 main types of task.
.PP
\fIACTION\fR
.IX Subsection "ACTION"
.PP
An action is the most simple unit used in composition. An action is essentially
a name and a codeblock to run.
.PP
\fIGROUP\fR
.IX Subsection "GROUP"
.PP
A group is a task that is composed of other tasks.
.SH EXPORTS
.IX Header "EXPORTS"
All exports are optional, you must request the ones you want.
.ie n .IP "$parsed = parse_args(args => \e@args)" 4
.el .IP "\f(CW$parsed\fR = parse_args(args => \e@args)" 4
.IX Item "$parsed = parse_args(args => @args)"
.PD 0
.ie n .IP "$parsed = parse_args(args => \e@args, level => $L)" 4
.el .IP "\f(CW$parsed\fR = parse_args(args => \e@args, level => \f(CW$L\fR)" 4
.IX Item "$parsed = parse_args(args => @args, level => $L)"
.ie n .IP "$parsed = parse_args(args => \e@args, caller => [caller($L)])" 4
.el .IP "\f(CW$parsed\fR = parse_args(args => \e@args, caller => [caller($L)])" 4
.IX Item "$parsed = parse_args(args => @args, caller => [caller($L)])"
.PD
This will parse a "typical" task builders arguments. The \f(CW@args\fR array MUST
contain a name (plain scalar containing text) and also a single CODE reference.
The \f(CW@args\fR array MAY also contain any quantity of line numbers or hashrefs.
The resulting data structure will be a single hashref with all the provided
hashrefs squashed together, and the 'name', 'code', 'lines' and 'frame' keys
set from other arguments.
.Sp
.Vb 3
\&    {
\&        # All hashrefs from @args get squashed together:
\&        %squashed_input_hashref_data,
\&
\&        # @args must have exactly 1 plaintext scalar that is not a number, it
\&        # is considered the name:
\&        name => \*(Aqname from input args\*(Aq
\&
\&        # Integer values are treated as line numbers
\&        lines => [ 35, 44 ],
\&
\&        # Exactly 1 coderef must be provided in @args:
\&        code => \e&some_code,
\&
\&        # \*(Aqframe\*(Aq contains the \*(Aqcaller\*(Aq data. This may be passed in directly,
\&        # obtained from the \*(Aqlevel\*(Aq parameter, or automatically deduced.
\&        frame => [\*(AqA::Package\*(Aq, \*(Aqa_file.pm\*(Aq, 42, ...],
\&    }
.Ve
.ie n .IP "$build = init_root($pkg, %args)" 4
.el .IP "\f(CW$build\fR = init_root($pkg, \f(CW%args\fR)" 4
.IX Item "$build = init_root($pkg, %args)"
This will initialize (or return the existing) a build for the specified
package. \f(CW%args\fR get passed into the Test2::Workflow::Build constructor.
This uses the following defaults (which can be overridden using \f(CW%args\fR):
.Sp
.Vb 5
\&    name    => $pkg,
\&    flat    => 1,
\&    iso     => 0,
\&    async   => 0,
\&    is_root => 1,
.Ve
.Sp
Note that \f(CW%args\fR is completely ignored if the package build has already been
initialized.
.ie n .IP "$build = root_build($pkg)" 4
.el .IP "\f(CW$build\fR = root_build($pkg)" 4
.IX Item "$build = root_build($pkg)"
This will return the root build for the specified package.
.ie n .IP "$build = \fBcurrent_build()\fR" 4
.el .IP "\f(CW$build\fR = \fBcurrent_build()\fR" 4
.IX Item "$build = current_build()"
This will return the build currently at the top of the build stack (or undef).
.ie n .IP "$build = build($name, \e%params, sub { ... })" 4
.el .IP "\f(CW$build\fR = build($name, \e%params, sub { ... })" 4
.IX Item "$build = build($name, %params, sub { ... })"
This will push a new build object onto the build stash then run the provided
codeblock. Once the codeblock has finished running the build will be popped off
the stack and returned.
.Sp
See \f(CWparse_args()\fR for details about argument processing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP Test2::Tools::Spec 4
.IX Item "Test2::Tools::Spec"
Test2::Tools::Spec is an implementation of RSPEC using this library.
.SH SOURCE
.IX Header "SOURCE"
The source code repository for Test2\-Workflow 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 <exodist7@gmail.com>.
.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