1Test::Stream::Workflow(U3s)er Contributed Perl DocumentatTieosnt::Stream::Workflow(3)
2
6 Test::Stream::Workflow - Interface for writing 'workflow' tools such as
7 RSPEC implementations that all play nicely together.
8
10 This distribution is deprecated in favor of Test2, Test2::Suite, and
11 Test2::Workflow.
12 See Test::Stream::Manual::ToTest2 for a conversion guide.
14
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
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
30 package My::Workflow::Tool;
31 use Test::Stream::Workflow qw/gen_unit_builder/;
32 use Test::Stream::Exporter;
34 # Create a wrapping tool
36 export my_wrapper => gen_unit_builder('simple' => qw/buildup teardown/);
37 no Test::Stream::Exporter;
39 To use it:
41 use My::Workflow::Tool qw/my_wrapper/;
43 my_wrapper foo => sub {
45 my $inner = shift;
46 ...
47 $inner->();
48 ...
49 };
50
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 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 See Test::Stream::Workflow::Unit.
66 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 See Test::Stream::Workflow::Meta where the primary unit is stored.
72 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 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 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 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
98 All exports are optional, you must request the ones you want.
99 BUILD STACK
101 $unit = workflow_build()
102 Get the unit at the top of the build stack, if any.
103 $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 push_workflow_build($unit)
109 Push a unit onto the build stack.
110 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 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 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 $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 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 $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 META DATA
150 $meta = workflow_meta()
151 Get the Test::Stream::Workflow::Meta object associated with the
152 current package.
153 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 workflow_runner_args(\@args)
162 Arguments that should be passed to the "run()" method of your
163 runner.
164 workflow_run()
166 Run the workflow now.
167 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 $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 Stashes:
191 primary
193 A primary action.
194 modify
196 Something to modify the primary actions.
197 buildup
199 Something to run before the primary actions.
200 teardown
202 Something to run after the primary actions.
203 ($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 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
221 Test::Stream::Plugin::Spec
222 Test::Stream::Plugin::Spec is an implementation of RSPEC using this
223 library.
224
226 The source code repository for Test::Stream can be found at
227 http://github.com/Test-More/Test-Stream/.
228
230 Chad Granum <exodist@cpan.org>
231
233 Chad Granum <exodist@cpan.org>
234
236 Copyright 2015 Chad Granum <exodist7@gmail.com>.
237 This program is free software; you can redistribute it and/or modify it
239 under the same terms as Perl itself.
240 See http://dev.perl.org/licenses/
242perl v5.32.1 2021-01-27 Test::Stream::Workflow(3)