1Test2::Tools::Spec(3) User Contributed Perl DocumentationTest2::Tools::Spec(3)
2
3
4

NAME

6       Test2::Tools::Spec - RSPEC implementation on top of Test2::Workflow
7

DESCRIPTION

9       This uses Test2::Workflow to implement an RSPEC variant. This variant
10       supports isolation and/or concurrency via forking or threads.
11

SYNOPSIS

13           use Test2::Bundle::Extended;
14           use Test2::Tools::Spec;
15
16           describe foo => sub {
17               before_all  once => sub { ... };
18               before_each many => sub { ... };
19
20               after_all  once => sub { ... };
21               after_each many => sub { ... };
22
23               case condition_a => sub { ... };
24               case condition_b => sub { ... };
25
26               tests foo => sub { ... };
27               tests bar => sub { ... };
28           };
29
30           done_testing;
31

EXPORTS

33       All of these use the same argument pattern. The first argument must
34       always be a name for the block. The last argument must always be a code
35       reference.  Optionally a configuration hash can be inserted between the
36       name and the code reference.
37
38           FUNCTION "name" => sub { ... };
39
40           FUNCTION "name" => {...}, sub { ... };
41
42       NAME
43           The first argument to a Test2::Tools::Spec function MUST be a name.
44           The name does not need to be unique.
45
46       PARAMS
47           This argument is optional. If present this should be a hashref.
48
49           Here are the valid keys for the hashref:
50
51           flat => $bool
52                   If this is set to true then the block will not render as a
53                   subtest, instead the events will be inline with the parent
54                   subtest (or main test).
55
56           async => $bool
57                   Set this to true to mark a block as being capable of
58                   running concurrently with other test blocks. This does not
59                   mean the block WILL be run concurrently, just that it can
60                   be.
61
62           iso => $bool
63                   Set this to true if the block MUST be run in isolation. If
64                   this is true then the block will run in its own forked
65                   process.
66
67                   These tests will be skipped on any platform that does not
68                   have true forking, or working/enabled threads.
69
70                   Threads will ONLY be used if the T2_WORKFLOW_USE_THREADS
71                   env var is set. Thread tests are only run if the
72                   T2_DO_THREAD_TESTS env var is set.
73
74           todo => $reason
75                   Use this to mark an entire block as TODO.
76
77           skip => $reason
78                   Use this to prevent a block from running at all.
79
80       CODEREF
81           This argument is required. This should be a code reference that
82           will run some assertions.
83
84   ESSENTIALS
85       tests NAME => sub { ... }
86       tests NAME => \%params, sub { ... }
87       tests($NAME, \%PARAMS, \&CODE)
88       it NAME => sub { ... }
89       it NAME => \%params, sub { ... }
90       it($NAME, \%PARAMS, \&CODE)
91           This defines a test block. Test blocks are essentially subtests.
92           All test blocks will be run, and are expected to produce events.
93           Test blocks can run multiple times if the case() function is also
94           used.
95
96           it() is an alias to tests().
97
98           These ARE NOT inherited by nested describe blocks.
99
100       case NAME => sub { ... }
101       case NAME => \%params, sub { ... }
102       case($NAME, \%PARAMS, \&CODE)
103           This lets you specify multiple conditions in which the test blocks
104           should be run. Every test block within the same group ("describe")
105           will be run once per case.
106
107           These ARE NOT inherited by nested describe blocks, but nested
108           describe blocks will be executed once per case.
109
110       before_each NAME => sub { ... }
111       before_each NAME => \%params, sub { ... }
112       before_each($NAME, \%PARAMS, \&CODE)
113           Specify a codeblock that should be run multiple times, once before
114           each tests() block is run. These will run AFTER case() blocks but
115           before tests() blocks.
116
117           These ARE inherited by nested describe blocks.
118
119       before_case NAME => sub { ... }
120       before_case NAME => \%params, sub { ... }
121       before_case($NAME, \%PARAMS, \&CODE)
122           Same as before_each(), except these blocks run BEFORE case()
123           blocks.
124
125           These ARE NOT inherited by nested describe blocks.
126
127       before_all NAME => sub { ... }
128       before_all NAME => \%params, sub { ... }
129       before_all($NAME, \%PARAMS, \&CODE)
130           Specify a codeblock that should be run once, before all the test
131           blocks run.
132
133           These ARE NOT inherited by nested describe blocks.
134
135       around_each NAME => sub { ... }
136       around_each NAME => \%params, sub { ... }
137       around_each($NAME, \%PARAMS, \&CODE)
138           Specify a codeblock that should wrap around each test block. These
139           blocks are run AFTER case blocks, but before test blocks.
140
141               around_each wrapit => sub {
142                   my $cont = shift;
143
144                   local %ENV = ( ... );
145
146                   $cont->();
147
148                   ...
149               };
150
151           The first argument to the codeblock will be a callback that MUST be
152           called somewhere inside the sub in order for nested items to run.
153
154           These ARE inherited by nested describe blocks.
155
156       around_case NAME => sub { ... }
157       around_case NAME => \%params, sub { ... }
158       around_case($NAME, \%PARAMS, \&CODE)
159           Same as "around_each" except these run BEFORE case blocks.
160
161           These ARE NOT inherited by nested describe blocks.
162
163       around_all NAME => sub { ... }
164       around_all NAME => \%params, sub { ... }
165       around_all($NAME, \%PARAMS, \&CODE)
166           Same as "around_each" except that it only runs once to wrap ALL
167           test blocks.
168
169           These ARE NOT inherited by nested describe blocks.
170
171       after_each NAME => sub { ... }
172       after_each NAME => \%params, sub { ... }
173       after_each($NAME, \%PARAMS, \&CODE)
174           Same as "before_each" except it runs right after each test block.
175
176           These ARE inherited by nested describe blocks.
177
178       after_case NAME => sub { ... }
179       after_case NAME => \%params, sub { ... }
180       after_case($NAME, \%PARAMS, \&CODE)
181           Same as "after_each" except it runs right after the case block, and
182           before the test block.
183
184           These ARE NOT inherited by nested describe blocks.
185
186       after_all NAME => sub { ... }
187       after_all NAME => \%params, sub { ... }
188       after_all($NAME, \%PARAMS, \&CODE)
189           Same as "before_all" except it runs after all test blocks have been
190           run.
191
192           These ARE NOT inherited by nested describe blocks.
193
194   SHORTCUTS
195       These are shortcuts. Each of these is the same as tests() except some
196       parameters are added for you.
197
198       These are NOT exported by default/.
199
200       mini NAME => sub { ... }
201           Same as:
202
203               tests NAME => { flat => 1 }, sub { ... }
204
205       iso NAME => sub { ... }
206           Same as:
207
208               tests NAME => { iso => 1 }, sub { ... }
209
210       miso NAME => sub { ... }
211           Same as:
212
213               tests NAME => { mini => 1, iso => 1 }, sub { ... }
214
215       async NAME => sub { ... }
216           Same as:
217
218               tests NAME => { async => 1 }, sub { ... }
219
220           Note: This conflicts with the async() exported from threads. Don't
221           import both.
222
223       masync NAME => sub { ... }
224           Same as:
225
226               tests NAME => { minit => 1, async => 1 }, sub { ... }
227
228   CUSTOM ATTRIBUTE DEFAULTS
229       Sometimes you want to apply default attributes to all tests() or case()
230       blocks. This can be done, and is lexical to your describe or package
231       root!
232
233           use Test2::Bundle::Extended;
234           use Test2::Tools::Spec ':ALL';
235
236           # All 'tests' blocks after this declaration will have C<<iso => 1>> by default
237           spec_defaults tests => (iso => 1);
238
239           tests foo => sub { ... }; # isolated
240
241           tests foo, {iso => 0}, sub { ... }; # Not isolated
242
243           spec_defaults tests => (iso => 0); # Turn it off again
244
245       Defaults are inherited by nested describe blocks. You can also override
246       the defaults for the scope of the describe:
247
248           spec_defaults tests => (iso => 1);
249
250           describe foo => sub {
251               spec_defaults tests => (async => 1); # Scoped to this describe and any child describes
252
253               tests bar => sub { ... }; # both iso and async
254           };
255
256           tests baz => sub { ... }; # Just iso, no async.
257
258       You can apply defaults to any type of blocks:
259
260           spec_defaults case => (iso => 1); # All cases are 'iso';
261
262       Defaults are not inherited when a builder's return is captured.
263
264           spec_defaults tests => (iso => 1);
265
266           # Note we are not calling this in void context, that is the key here.
267           my $d = describe foo => {
268               tests bar => sub { ... }; # Not iso
269           };
270

EXECUTION ORDER

272       As each function is encountered it executes, just like any other
273       function. The describe() function will immediately execute the
274       codeblock it is given. All other functions will stash their codeblocks
275       to be run later. When done_testing() is run the workflow will be
276       compiled, at which point all other blocks will run.
277
278       Here is an overview of the order in which blocks get called once
279       compiled (at done_testing()).
280
281           before_all
282               for-each-case {
283                   before_case
284                       case
285                   after_case
286
287                   # AND/OR nested describes
288                   before_each
289                       tests
290                   after_each
291               }
292           after_all
293

SOURCE

295       The source code repository for Test2-Workflow can be found at
296       https://github.com/Test-More/Test2-Suite/.
297

MAINTAINERS

299       Chad Granum <exodist@cpan.org>
300

AUTHORS

302       Chad Granum <exodist@cpan.org>
303

COPYRIGHT

305       Copyright 2018 Chad Granum <exodist7@gmail.com>.
306
307       This program is free software; you can redistribute it and/or modify it
308       under the same terms as Perl itself.
309
310       See http://dev.perl.org/licenses/
311
312
313
314perl v5.36.0                      2023-03-23             Test2::Tools::Spec(3)