1Test::Stream::Plugin::SUpseecr(3C)ontributed Perl DocumeTnetsatt:i:oSntream::Plugin::Spec(3)
2
3
4

NAME

6       Test::Stream::Plugin::Spec - SPEC testing tools
7

EXPERIMENTAL CODE WARNING

9       "This module is still EXPERIMENTAL". Test-Stream is now stable, but
10       this particular module is still experimental. You are still free to use
11       this module, but you have been warned that it may change in backwords
12       incompatible ways.  This message will be removed from this modules POD
13       once it is considered stable.
14

DEPRECATED

16       This distribution is deprecated in favor of Test2, Test2::Suite, and
17       Test2::Workflow.
18
19       See Test::Stream::Manual::ToTest2 for a conversion guide.
20

DESCRIPTION

SYNOPSIS

23           use Test::Stream qw/-V1 Spec/
24
25           describe fruit_shipment => sub {
26               my $crates;
27               before_all unload_crates => sub { $crates = get_crates() };
28               after_all deliver_crates => sub { deliver($crates) };
29
30               my $fruit;
31               for my $f ($crates->types) { # 'pear' and 'apple'
32                   case $f => sub { $fruit = $f };
33               }
34
35               my $crate;
36               before_each open_crate => sub { $crate = $crates->open_first($fruit) };
37               after_each close_crate => sub { $crates->store($crate) };
38
39               tests squishability => sub {
40                   my $sample = $crate->grab();
41                   ok($sample->squishability > 5, "squish rating is greater than 5");
42                   ok($sample->squishability < 10, "squish rating is less than 10");
43               };
44
45               tests flavor => sub {
46                   my $sample = $crate->grab();
47                   ok($sample->is_tasty, "sample is tasty");
48                   ok(!$sample->is_sour, "sample is not sour");
49               };
50
51               tests ripeness => sub {
52                   my $sample1 = $crate->grab();
53                   my $sample2 = $crate->grab();
54
55                   my $overripe  = grep { $_->is_overripe }  $sample1, $sample2;
56                   my $underripe = grep { $_->is_underripe } $sample1, $sample2;
57
58                   ok($overripe  < 2, "at least 1 sample is not overripe");
59                   ok($underripe < 2, "at least 1 sample is not underripe");
60               };
61           };
62
63           done_testing;
64
65       In this sample we are describing a fruit shipment. Before anything else
66       we unload the crates. Next we handle 2 types of fruit, a crate of pears
67       and a crate of apples. For each create we need to run tests on
68       squishability, flavor, and ripeness. In order to run these tests the
69       creates need to be opened, when the tests are done the crates need to
70       be closed again.
71
72       We use the before_all and after_all to specify the first and last tasks
73       to be run, each one will run exactly once. The 3 sets of tests will be
74       run once per fruit type, we have cases for pears and apples, so in
75       total there will be 6 sets of tests run, 3 per fruit type. Opening and
76       closing the crate is something we need to do for each test block, so we
77       use before_each and after_each.
78
79       Each test block needs unique samples, so the sample is aquired within
80       the test.  We do not use a before_each as some tests require different
81       numbers of samples.
82

EXPORTS

84       All exports have the exact same syntax, there are 2 forms:
85
86           FUNCTION($NAME, \&CODE);
87           FUNCTION($NAME, \%PARAMS, \&CODE);
88
89       Both can also be used in a style that is more pleasingto the eye:
90
91           FUNCTION $NAME => sub { ... };
92           FUNCTION $NAME => {...}, sub { ... }
93
94       The name and codeblock are required. Optionally you can provide a
95       hashref of parameters between the name and coderef with parameters.
96       Valid parameters depends on what runner is used, but the parameters
97       supported by default are:
98
99       Note: The default runner is Test::Stream::Workflow::Runner.
100
101       todo => 'reason'
102           This will mark the entire block as todo with the given reason. This
103           parameter is inherited by nested blocks.
104
105       skip => 'reason'
106           This will skip the entire block, it will generate a single 'Ok'
107           event with the skip reason set.
108
109       iso => $bool
110       isolate => $bool
111           This tells the runner to isolate the task before running the block.
112           This allows you to isolate blocks that may modify state in ways
113           that should not be seen by later tests. Isolation is achieved
114           either by forking, or by spawning a child thread, depending on the
115           platform. If no isolation method is available the block will simply
116           be skipped.
117
118           CAVEAT: Since the isolation may be threads (specially if you are on
119           windows) it may fail to isolate shared variables. If you use
120           variables that are shared between threads you cannot rely on this
121           isolation mechanism.
122
123       Note: The tests you declare are deferred, that is they run after
124       everything else is done, typically when you call "done_testing".
125
126   TEST DECLARATIONS
127       Test declarations are used to declare blocks of tests. You can put
128       pretty much anything you want inside a test block, the only exceptions
129       to this is that other test blocks, groups, modifiers, etc, cannot be
130       specified inside the test block.
131
132       If a test block does not produce any events then it will be considered
133       an error. Test blocks are run as subtests.
134
135       tests $name => sub { ... }
136       it $name => sub { ... }
137       tests $name => \%params, sub { ... }
138       it $name => \%params, sub { ... }
139           "tests()" and "it()" are both aliases to the same function. The
140           name "tests()" is present as the authors preference. "it()" is
141           present to reflect the name used in RSPEC for the Ruby programming
142           language.
143
144           Note: The subs get no arguments, and their return is ignored.
145
146   TEST SETUP AND TEARDOWN
147       These blocks attach themselves to test blocks. The setup/teardown will
148       run once for each test block. These are all inherited by test blocks
149       declared in nested groups.
150
151       before_each $name => sub { ... }
152           Declare a setup that will run before each test block is run. Note:
153           This will run before any modifier.
154
155           Note: The subs get no arguments, and their return is ignored.
156
157       after_each $name => sub { ... }
158           Declare a teardown that will run after each test block.
159
160           Note: The subs get no arguments, and their return is ignored.
161
162       around_each $name => sub { ... }
163           Declare a setup+teardown that is wrapped around the test block.
164           This is useful if you want to localize a variable, or something
165           similar.
166
167               around_each foo => sub {
168                   my $inner = shift;
169
170                   local %ENV;
171
172                   # You need to call the 'inner' sub.
173                   $inner->();
174               };
175
176           Note: The subs get no arguments, and their return is ignored.
177
178   TEST MODIFIERS
179       case $name => sub { ... }
180           You can specify any number of cases that should be used. All test
181           blocks are run once per case. Cases are inherited by nested groups.
182
183           Note: The subs get no arguments, and their return is ignored.
184
185       TEST MODIFIER SETUP AND TEARDOWN
186
187       before_case $name => sub { ... }
188           Code to be run just before a case is run.
189
190           Note: The subs get no arguments, and their return is ignored.
191
192       after_case $name => sub { ... }
193           Code to be run just after a case is run (but before the test
194           block).
195
196           Note: The subs get no arguments, and their return is ignored.
197
198       around_case $name => sub { ... }
199           Code that wraps around the case.
200
201               around_case foo => sub {
202                   my $inner = shift;
203
204                   local %ENV;
205
206                   # You need to call the 'inner' sub.
207                   $inner->();
208               };
209
210           Note: The subs get no arguments, and their return is ignored.
211
212   TEST GROUPS
213       describe $name => sub { ... }
214       cases $name => sub { ... }
215           "describe()" and "cases()" are both aliases to the same thing.
216
217           These can be used to create groups of test block along with
218           setup/teardown subs. The cases, setups, and teardowns will not
219           effect test blocks outside the group. All cases, setups, and
220           teardown will be inherited by any nested group.
221
222           Note: Group subs are run as they are encountered, unlike test
223           blocks which are run at the very end of the test script.
224
225           Note: The subs get no arguments, and their return is ignored.
226
227   GROUP MODIFIERS
228       before_all $name => sub { ... }
229           Specify a setup that gets run once at the start of the test group.
230
231           Note: The subs get no arguments, and their return is ignored.
232
233       after_all $name => sub { ... }
234           Specify a teardown that gets run once at the end of the test group.
235
236           Note: The subs get no arguments, and their return is ignored.
237
238       around_all $name => sub { ... }
239           Specify a teardown that gets run once, around the test group.
240
241               around_all foo => sub {
242                   my $inner = shift;
243
244                   local %ENV;
245
246                   # You need to call the 'inner' sub.
247                   $inner->();
248               };
249
250           Note: The subs get no arguments, and their return is ignored.
251

NOTE ON RUN ORDER

253       Within a test group (the main package counts as a group) things run in
254       this order:
255
256       group blocks (describe, cases)
257       END OF SCRIPT (done_testing called)
258       before_all + around_all starts
259           before_each + around_each starts
260               before_case + around_case starts
261                   case
262               after_case + around_case stops
263               tests/it
264           after_each + around_each stops
265       after_all + around_all stops
266

SOURCE

268       The source code repository for Test::Stream can be found at
269       http://github.com/Test-More/Test-Stream/.
270

MAINTAINERS

272       Chad Granum <exodist@cpan.org>
273

AUTHORS

275       Chad Granum <exodist@cpan.org>
276
278       Copyright 2015 Chad Granum <exodist7@gmail.com>.
279
280       This program is free software; you can redistribute it and/or modify it
281       under the same terms as Perl itself.
282
283       See http://dev.perl.org/licenses/
284
285
286
287perl v5.34.0                      2021-07-27     Test::Stream::Plugin::Spec(3)
Impressum