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 name
140 tests() is present as the authors preference. it() is present to
141 reflect the name used in RSPEC for the Ruby programming language.
142 Note: The subs get no arguments, and their return is ignored.
144 TEST SETUP AND TEARDOWN
146 These blocks attach themselves to test blocks. The setup/teardown will
147 run once for each test block. These are all inherited by test blocks
148 declared in nested groups.
149 before_each $name => sub { ... }
151 Declare a setup that will run before each test block is run. Note:
152 This will run before any modifier.
153 Note: The subs get no arguments, and their return is ignored.
155 after_each $name => sub { ... }
157 Declare a teardown that will run after each test block.
158 Note: The subs get no arguments, and their return is ignored.
160 around_each $name => sub { ... }
162 Declare a setup+teardown that is wrapped around the test block.
163 This is useful if you want to localize a variable, or something
164 similar.
165 around_each foo => sub {
167 my $inner = shift;
168 local %ENV;
170 # You need to call the 'inner' sub.
172 $inner->();
173 };
174 Note: The subs get no arguments, and their return is ignored.
176 TEST MODIFIERS
178 case $name => sub { ... }
179 You can specify any number of cases that should be used. All test
180 blocks are run once per case. Cases are inherited by nested groups.
181 Note: The subs get no arguments, and their return is ignored.
183 TEST MODIFIER SETUP AND TEARDOWN
185 before_case $name => sub { ... }
187 Code to be run just before a case is run.
188 Note: The subs get no arguments, and their return is ignored.
190 after_case $name => sub { ... }
192 Code to be run just after a case is run (but before the test
193 block).
194 Note: The subs get no arguments, and their return is ignored.
196 around_case $name => sub { ... }
198 Code that wraps around the case.
199 around_case foo => sub {
201 my $inner = shift;
202 local %ENV;
204 # You need to call the 'inner' sub.
206 $inner->();
207 };
208 Note: The subs get no arguments, and their return is ignored.
210 TEST GROUPS
212 describe $name => sub { ... }
213 cases $name => sub { ... }
214 describe() and cases() are both aliases to the same thing.
215 These can be used to create groups of test block along with
217 setup/teardown subs. The cases, setups, and teardowns will not
218 effect test blocks outside the group. All cases, setups, and
219 teardown will be inherited by any nested group.
220 Note: Group subs are run as they are encountered, unlike test
222 blocks which are run at the very end of the test script.
223 Note: The subs get no arguments, and their return is ignored.
225 GROUP MODIFIERS
227 before_all $name => sub { ... }
228 Specify a setup that gets run once at the start of the test group.
229 Note: The subs get no arguments, and their return is ignored.
231 after_all $name => sub { ... }
233 Specify a teardown that gets run once at the end of the test group.
234 Note: The subs get no arguments, and their return is ignored.
236 around_all $name => sub { ... }
238 Specify a teardown that gets run once, around the test group.
239 around_all foo => sub {
241 my $inner = shift;
242 local %ENV;
244 # You need to call the 'inner' sub.
246 $inner->();
247 };
248 Note: The subs get no arguments, and their return is ignored.
250
252 Within a test group (the main package counts as a group) things run in
253 this order:
254 group blocks (describe, cases)
256 END OF SCRIPT (done_testing called)
257 before_all + around_all starts
258 before_each + around_each starts
259 before_case + around_case starts
260 case
261 after_case + around_case stops
262 tests/it
263 after_each + around_each stops
264 after_all + around_all stops
265
267 The source code repository for Test::Stream can be found at
268 http://github.com/Test-More/Test-Stream/.
269
271 Chad Granum <exodist@cpan.org>
272
274 Chad Granum <exodist@cpan.org>
275
277 Copyright 2015 Chad Granum <exodist7@gmail.com>.
278 This program is free software; you can redistribute it and/or modify it
280 under the same terms as Perl itself.
281 See http://dev.perl.org/licenses/
283perl v5.38.0 2023-07-21 Test::Stream::Plugin::Spec(3)