1Test::Stream::Workflow(U3s)er Contributed Perl DocumentatTieosnt::Stream::Workflow(3)
2
3
4

NAME

6       Test::Stream::Workflow - Interface for writing 'workflow' tools such as
7       RSPEC implementations that all play nicely together.
8

DEPRECATED

10       This distribution is deprecated in favor of Test2, Test2::Suite, and
11       Test2::Workflow.
12
13       See Test::Stream::Manual::ToTest2 for a conversion guide.
14

EXPERIMENTAL CODE WARNING

16       "This module is still EXPERIMENTAL". Test-Stream is now stable, but
17       this particular module is still experimental. You are still free to use
18       this module, but you have been warned that it may change in backwords
19       incompatible ways.  This message will be removed from this modules POD
20       once it is considered stable.
21

DESCRIPTION

23       This module intends to do for 'workflow' test tools what Test::Builder
24       and Test::Stream do for general test tools. The problem with workflow
25       tools is that most do not play well together. This module is a very
26       generic/abstract look at workflows that allows tools to be built that
27       accomplish their workflows, but in a way that plays well with others.
28

SYNOPSIS

30           package My::Workflow::Tool;
31           use Test::Stream::Workflow qw/gen_unit_builder/;
32
33           use Test::Stream::Exporter;
34
35           # Create a wrapping tool
36           export my_wrapper => gen_unit_builder('simple' => qw/buildup teardown/);
37
38           no Test::Stream::Exporter;
39
40       To use it:
41
42           use My::Workflow::Tool qw/my_wrapper/;
43
44           my_wrapper foo => sub {
45               my $inner = shift;
46               ...
47               $inner->();
48               ...
49           };
50

IMPORTANT CONCEPTS

52       A workflow is a way of defining tests with scaffolding. Essentially you
53       are seperating your assertions and your setup/teardown/management code.
54       This results in a separation of concerns that can produce more
55       maintainable tests.  In addition each component of a workflow can be
56       re-usable and/or inheritable.
57
58   UNITS
59       Units are the small composable parts of a workflow. You can think of a
60       unit as a named function that does some work. What separates a unit
61       from a regular function is that it can have other units attashed to it
62       in various ways. A unit can also be a 'group' unit, which means it
63       contains other units as its primary work.
64
65       See Test::Stream::Workflow::Unit.
66
67   PACKAGE UNIT
68       The package unit is the root 'group' unit for your test package. All
69       other test units get put into the main package unit.
70
71       See Test::Stream::Workflow::Meta where the primary unit is stored.
72
73   BUILDS
74       Units are generally defined using a DSL (Domain Specific Language). In
75       this DSL you declare a unit, which gets added as the current build,
76       then run code which modifies that build to turn it into the unit you
77       need.
78
79   BUILD STACK
80       Builds can be defined within one another, as such the 'current' build
81       is whatever build is on top of the build stack, which is a private
82       array. There are low level functions exposed to give you control over
83       the stack if you need it, but in general you should use a higher level
84       tool.
85
86   TASK
87       A task is a composition of units to be run. The runner will compile you
88       units into task form, then run the compiled tasks.
89
90   VAR STASH
91       There is a var stash. The var stash is a stack of hashes. Every time a
92       task is run a new hash is pushed onto the stack. When a task is
93       complete the hash is popped and cleared. Workflow tools may use this
94       hash to store/define variables that will go away when the current task
95       is complete.
96

EXPORTS

98       All exports are optional, you must request the ones you want.
99
100   BUILD STACK
101       $unit = workflow_build()
102           Get the unit at the top of the build stack, if any.
103
104       $unit = workflow_current()
105           Get the unit at the top of the build stack, if there is none then
106           return the root unit for the package the function is called from.
107
108       push_workflow_build($unit)
109           Push a unit onto the build stack.
110
111       pop_workflow_build($unit)
112           Pop a unit from the build stack. You must provide the $unit you
113           expect to pop, and it must match the one at the top of the stack.
114
115   VAR STASH
116       $val = workflow_var($name)
117       $val = workflow_var($name, $val)
118       $val = workflow_var($name, \&default)
119           This function will get/set a variable in the var stash. If only a
120           name is provided then it will return the current value, or undef.
121           If you provide a value as the second argument then the value will
122           be set.
123
124           A coderef can be passed in as the second argument. If a coderef is
125           used it will be considered a default generator. If the variable
126           name already has a value then that value will be kept and returned.
127           If the variable has not been set then the coderef will be run and
128           the value it returns will be stored and returned.
129
130       $hr = push_workflow_vars()
131       push_workflow_vars($hr)
132           You can manually push a new hashref to the top of the vars stack.
133           If you do this you need to be sure to pop it before anything else
134           tries to pop any hash below yours in the stack. You can provide a
135           hashref to push, or it will create a new one for you.
136
137       pop_workflow_vars($hr)
138           This will let you manually pop the workflow vars stack. You must
139           provide a reference to the item you think is at the top of the
140           stack (the one you want to pop). If something else is on top of the
141           stack then an exception will be thrown.
142
143       $bool = has_workflow_vars()
144           Check if there is a workflow vars hash on the stack. This will
145           return false if there is nothing on the stack. Currently this
146           returns the number of items in the stack, but that may change so do
147           not depend on that behavior.
148
149   META DATA
150       $meta = workflow_meta()
151           Get the Test::Stream::Workflow::Meta object associated with the
152           current package.
153
154       workflow_runner($runner)
155           Set the runner to use. The runner can be a package name, or a
156           blessed object.  Whichever you provide, it must have a 'run'
157           method. The run method will be called directly on what you provide,
158           that is if you provide a package name then it will call
159           "$package->run()" "new()" will not be called for you.
160
161       workflow_runner_args(\@args)
162           Arguments that should be passed to the "run()" method of your
163           runner.
164
165       workflow_run()
166           Run the workflow now.
167
168   CREATING UNITS
169       $unit = group_builder($name, \%params, sub { ... })
170       $unit = group_builder($name, sub { ... })
171       group_builder($name, \%params, sub { ... })
172       group_builder($name, sub { ... })
173           The group builder will create a new unit with the given name and
174           parameters.  The new unit will be placed onto the build stack, and
175           the code reference you provide will be run. Once the code reference
176           returns the unit will be removed from the build stack. If called in
177           void context the unit will be added to the next unit on the build
178           stack, or to the package root unit. If called in any other context
179           the unit will be returned.
180
181       $sub = gen_unit_builder($callback, @stashes)
182           This will return a coderef that accepts the typical $name, optional
183           "\%params", and "\&code" arguments. The code returned will
184           construct your unit for you, and then insert it into the specified
185           stashes of the current build whenever it is called. Typically you
186           will only specify one stash, but you may combine "buildup" and
187           "teardown" if the builder you are creating is supposed to wrap
188           other units.
189
190           Stashes:
191
192           primary
193               A primary action.
194
195           modify
196               Something to modify the primary actions.
197
198           buildup
199               Something to run before the primary actions.
200
201           teardown
202               Something to run after the primary actions.
203
204       ($unit, $code, $caller) = new_proto_unit(\%params)
205           level => 1
206           caller => [caller($level)]
207           args => [$name, \%params, \&code]
208           args => [$name, \&code]
209           set_primary => $bool
210           unit => \%attributes
211               This is used under the hood by "gen_unit_builder()". This will
212               parse the 2 or 3 typical input arguments, verify them, and
213               return a new Test::Stream::Workflow::Unit, the coderef that was
214               passed in, and a caller arrayref.
215
216               If you use this it is your job to put the unit where it should
217               be. Normally "gen_unit_builder" and "group_builder" are all you
218               should need.
219

SEE ALSO

221       Test::Stream::Plugin::Spec
222           Test::Stream::Plugin::Spec is an implementation of RSPEC using this
223           library.
224

SOURCE

226       The source code repository for Test::Stream can be found at
227       http://github.com/Test-More/Test-Stream/.
228

MAINTAINERS

230       Chad Granum <exodist@cpan.org>
231

AUTHORS

233       Chad Granum <exodist@cpan.org>
234
236       Copyright 2015 Chad Granum <exodist7@gmail.com>.
237
238       This program is free software; you can redistribute it and/or modify it
239       under the same terms as Perl itself.
240
241       See http://dev.perl.org/licenses/
242
243
244
245perl v5.30.1                      2020-01-30         Test::Stream::Workflow(3)
Impressum