1Test::Stream::Plugin::SUpseecr(3C)ontributed Perl DocumeTnetsatt:i:oSntream::Plugin::Spec(3)
2
6 Test::Stream::Plugin::Spec - SPEC testing tools
7
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
16 This distribution is deprecated in favor of Test2, Test2::Suite, and
17 Test2::Workflow.
18 See Test::Stream::Manual::ToTest2 for a conversion guide.
20
23 use Test::Stream qw/-V1 Spec/
24 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 my $fruit;
31 for my $f ($crates->types) { # 'pear' and 'apple'
32 case $f => sub { $fruit = $f };
33 }
34 my $crate;
36 before_each open_crate => sub { $crate = $crates->open_first($fruit) };
37 after_each close_crate => sub { $crates->store($crate) };
38 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 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 tests ripeness => sub {
52 my $sample1 = $crate->grab();
53 my $sample2 = $crate->grab();
54 my $overripe = grep { $_->is_overripe } $sample1, $sample2;
56 my $underripe = grep { $_->is_underripe } $sample1, $sample2;
57 ok($overripe < 2, "at least 1 sample is not overripe");
59 ok($underripe < 2, "at least 1 sample is not underripe");
60 };
61 };
62 done_testing;
64 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 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 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
84 All exports have the exact same syntax, there are 2 forms:
85 FUNCTION($NAME, \&CODE);
87 FUNCTION($NAME, \%PARAMS, \&CODE);
88 Both can also be used in a style that is more pleasingto the eye:
90 FUNCTION $NAME => sub { ... };
92 FUNCTION $NAME => {...}, sub { ... }
93 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 Note: The default runner is Test::Stream::Workflow::Runner.
100 todo => 'reason'
102 This will mark the entire block as todo with the given reason. This
103 parameter is inherited by nested blocks.
104 skip => 'reason'
106 This will skip the entire block, it will generate a single 'Ok'
107 event with the skip reason set.
108 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 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 Note: The tests you declare are deferred, that is they run after
124 everything else is done, typically when you call "done_testing".
125 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 If a test block does not produce any events then it will be considered
133 an error. Test blocks are run as subtests.
134 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 Note: The subs get no arguments, and their return is ignored.
145 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 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 Note: The subs get no arguments, and their return is ignored.
156 after_each $name => sub { ... }
158 Declare a teardown that will run after each test block.
159 Note: The subs get no arguments, and their return is ignored.
161 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 around_each foo => sub {
168 my $inner = shift;
169 local %ENV;
171 # You need to call the 'inner' sub.
173 $inner->();
174 };
175 Note: The subs get no arguments, and their return is ignored.
177 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 Note: The subs get no arguments, and their return is ignored.
184 TEST MODIFIER SETUP AND TEARDOWN
186 before_case $name => sub { ... }
188 Code to be run just before a case is run.
189 Note: The subs get no arguments, and their return is ignored.
191 after_case $name => sub { ... }
193 Code to be run just after a case is run (but before the test
194 block).
195 Note: The subs get no arguments, and their return is ignored.
197 around_case $name => sub { ... }
199 Code that wraps around the case.
200 around_case foo => sub {
202 my $inner = shift;
203 local %ENV;
205 # You need to call the 'inner' sub.
207 $inner->();
208 };
209 Note: The subs get no arguments, and their return is ignored.
211 TEST GROUPS
213 describe $name => sub { ... }
214 cases $name => sub { ... }
215 "describe()" and "cases()" are both aliases to the same thing.
216 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 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 Note: The subs get no arguments, and their return is ignored.
226 GROUP MODIFIERS
228 before_all $name => sub { ... }
229 Specify a setup that gets run once at the start of the test group.
230 Note: The subs get no arguments, and their return is ignored.
232 after_all $name => sub { ... }
234 Specify a teardown that gets run once at the end of the test group.
235 Note: The subs get no arguments, and their return is ignored.
237 around_all $name => sub { ... }
239 Specify a teardown that gets run once, around the test group.
240 around_all foo => sub {
242 my $inner = shift;
243 local %ENV;
245 # You need to call the 'inner' sub.
247 $inner->();
248 };
249 Note: The subs get no arguments, and their return is ignored.
251
253 Within a test group (the main package counts as a group) things run in
254 this order:
255 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
268 The source code repository for Test::Stream can be found at
269 http://github.com/Test-More/Test-Stream/.
270
272 Chad Granum <exodist@cpan.org>
273
275 Chad Granum <exodist@cpan.org>
276
278 Copyright 2015 Chad Granum <exodist7@gmail.com>.
279 This program is free software; you can redistribute it and/or modify it
281 under the same terms as Perl itself.
282 See http://dev.perl.org/licenses/
284perl v5.32.0 2020-07-28 Test::Stream::Plugin::Spec(3)