1Test::Spec(3)         User Contributed Perl Documentation        Test::Spec(3)
2
3
4

NAME

6       Test::Spec - Write tests in a declarative specification style
7

SYNOPSIS

9         use Test::Spec; # automatically turns on strict and warnings
10
11         describe "A date" => sub {
12
13           my $date;
14
15           describe "in a leap year" => sub {
16
17             before each => sub {
18               $date = DateTime->new(year => 2000, month => 2, day => 28);
19             };
20
21             it "should know that it is in a leap year" => sub {
22               ok($date->is_leap_year);
23             };
24
25             it "should recognize Feb. 29" => sub {
26               is($date->add(days => 1)->day, 29);
27             };
28
29           };
30
31           describe "not in a leap year" => sub {
32             before each => sub {
33               $date = DateTime->new(year => 2001, month => 2, day => 28);
34             };
35
36             it "should know that it is NOT in a leap year" => sub {
37               ok(!$date->is_leap_year);
38             };
39
40             it "should NOT recognize Feb. 29" => sub {
41               is($date->add(days => 1)->day, 1);
42             };
43           };
44
45         };
46
47         runtests unless caller;
48
49         # Generates the following output:
50         # ok 1 - A date in a leap year should know that it is in a leap year
51         # ok 2 - A date in a leap year should recognize Feb. 29
52         # ok 3 - A date not in a leap year should know that it is NOT in a leap year
53         # ok 4 - A date not in a leap year should NOT recognize Feb. 29
54         # 1..4
55

DESCRIPTION

57       This is a declarative specification-style testing system for behavior-
58       driven development (BDD) in Perl. The tests (a.k.a. examples) are named
59       with strings instead of subroutine names, so your fingers will suffer
60       less fatigue from underscore-itis, with the side benefit that the test
61       reports are more legible.
62
63       This module is inspired by and borrows heavily from RSpec
64       <http://rspec.info/documentation>, a BDD tool for the Ruby programming
65       language.
66
67   EXPORTS
68       When given no list (i.e. "use Test::Spec;"), this class will export:
69
70       •   Spec definition functions
71
72           These are the functions you will use to define behaviors and run
73           your specs: "describe", "it", "they", "before", "after",
74           "runtests", "share", "shared_examples_for",
75           "it_should_behave_like", and "spec_helper".
76
77       •   The stub/mock functions in Test::Spec::Mocks.
78
79       •   Everything that Test::More normally exports
80
81           This includes "ok", "is" and friends. You'll use these to assert
82           correct behavior.
83
84       •   Everything that Test::Deep normally exports
85
86           More assertions including "cmp_deeply".
87
88       •   Everything that "Test::Trap" normally exports
89
90           The "trap()" function, which let you test behaviors that call
91           "exit()" and other hard things like that. "A block eval on
92           steroids."
93
94       If you specify an import list, only functions directly from
95       "Test::Spec" (those documented below) are available.
96
97   FUNCTIONS
98       runtests
99       runtests(@patterns)
100           Runs all the examples whose descriptions match one of the (non
101           case-sensitive) regular expressions in @patterns. If @patterns is
102           not provided, runs all examples. The environment variable "SPEC"
103           will be used as a default pattern if present.
104
105           If called as a function (i.e. not a method call with "->"),
106           "runtests" will autodetect the package from which it is called and
107           run that package's examples. A useful idiom is:
108
109             runtests unless caller;
110
111           which will run the examples when the file is loaded as a script
112           (for example, by running it from the command line), but not when it
113           is loaded as a module (with "require" or "use").
114
115       describe DESCRIPTION => CODE
116       describe CODE
117           Defines a specification context under which examples and more
118           descriptions can be defined.  All examples must come inside a
119           "describe" block.
120
121           "describe" blocks can be nested to DRY up your specs.
122               For large specifications, "describe" blocks can save you a lot
123               of duplication:
124
125                 describe "A User object" => sub {
126                   my $user;
127                   before sub {
128                     $user = User->new;
129                   };
130                   describe "from a web form" => sub {
131                     before sub {
132                       $user->init_from_tree({ username => "bbill", ... });
133                     };
134                     it "should read its attributes from the form";
135                     describe "when saving" => sub {
136                       it "should require a unique username";
137                       it "should require a password";
138                     };
139                   };
140                 };
141
142               The setup work done in each "before" block cascades from one
143               level to the next, so you don't have to make a call to some
144               initialization function manually in each test. It's done
145               automatically based on context.
146
147           Using describe blocks improves legibility without requiring more
148           typing.
149               The name of the context will be included by default in the
150               success/failure report generated by Test::Builder-based testing
151               methods (e.g.  Test::More's ok() function).  For an example
152               like this:
153
154                 describe "An unladen swallow" => sub {
155                   it "has an airspeed of 11 meters per second" => sub {
156                     is($swallow->airspeed, "11m/s");
157                   };
158                 };
159
160               The output generated is:
161
162                 ok 1 - An unladen swallow has an airspeed of 11 meters per second
163
164               Contrast this to the following test case to generate the same
165               output:
166
167                 sub unladen_swallow_airspeed : Test {
168                   is($swallow->airspeed, "11m/s",
169                      "An unladen swallow has an airspeed of 11 meters per second");
170                 }
171
172           "describe" blocks execute in the order in which they are defined.
173           Multiple "describe" blocks with the same name are allowed. They do
174           not replace each other, rather subsequent "describe"s extend the
175           existing one of the same name.
176
177       context
178           An alias for "describe()".
179
180       xdescribe
181           Specification contexts may be disabled by calling "xdescribe"
182           instead of "describe()". All examples inside an "xdescribe" are
183           reported as "# TODO (disabled)", which prevents Test::Harness/prove
184           from counting them as failures.
185
186       xcontext
187           An alias for "xdescribe()".
188
189       it SPECIFICATION => CODE
190       it CODE
191       it TODO_SPECIFICATION
192           Defines an example to be tested.  Despite its awkward name, "it"
193           allows a natural (in my opinion) way to describe expected behavior:
194
195             describe "A captive of Buffalo Bill" => sub {
196               it "puts the lotion on its skin" => sub {
197                 ...
198               };
199               it "puts the lotion in the basket"; # TODO
200             };
201
202           If a code reference is not passed, the specification is assumed to
203           be unimplemented and will be reported as "TODO (unimplemented)" in
204           the test results (see "todo_skip" in Test::Builder. TODO tests
205           report as skipped, not failed.
206
207       they SPECIFICATION => CODE
208       they CODE
209       they TODO_SPECIFICATION
210           An alias for "it".  This is useful for describing behavior for
211           groups of items, so the verb agrees with the noun:
212
213             describe "Captives of Buffalo Bill" => sub {
214               they "put the lotion on their skin" => sub {
215                 ...
216               };
217               they "put the lotion in the basket"; # TODO
218             };
219
220       xit/xthey
221           Examples may be disabled by calling xit()/xthey() instead of
222           it()/they().  These examples are reported as "# TODO (disabled)",
223           which prevents Test::Harness/prove from counting them as failures.
224
225       before each => CODE
226       before all => CODE
227       before CODE
228           Defines code to be run before tests in the current describe block
229           are run. If "each" is specified, CODE will be re-executed for every
230           test in the context. If "all" is specified, CODE will only be
231           executed before the first test.
232
233           The default is "each", due to this logic presented in RSpec's
234           documentation:
235
236           "It is very tempting to use before(:all) and after(:all) for
237           situations in which it is not appropriate. before(:all) shares some
238           (not all) state across multiple examples. This means that the
239           examples become bound together, which is an absolute no-no in
240           testing. You should really only ever use before(:all) to set up
241           things that are global collaborators but not the things that you
242           are describing in the examples.
243
244           The most common cases of abuse are database access and/or fixture
245           setup.  Every example that accesses the database should start with
246           a clean slate, otherwise the examples become brittle and start to
247           lose their value with false negatives and, worse, false positives."
248
249           (<http://rspec.info/documentation/before_and_after.html>)
250
251           There is no restriction on having multiple before blocks.  They
252           will run in sequence within their respective "each" or "all"
253           groups.  "before "all"" blocks run before "before "each"" blocks.
254
255       after each => CODE
256       after all => CODE
257       after CODE
258           Like "before", but backwards.  Runs CODE after each or all tests,
259           respectively.  The default is "each".
260
261           "after "all"" blocks run after "after "each"" blocks.
262
263       around CODE
264           Defines code to be run around tests in the current describe block
265           are run. This code must call "yield"..
266
267             our $var = 0;
268
269             describe "Something" => sub {
270               around {
271                 local $var = 1;
272                 yield;
273               };
274
275               it "should have localized var" => sub {
276                 is $var, 1;
277               };
278             };
279
280           This CODE will run around each example.
281
282       yield
283           Runs examples in context of "around" block.
284
285       shared_examples_for DESCRIPTION => CODE
286           Defines a group of examples that can later be included in
287           "describe" blocks or other "shared_examples_for" blocks. See
288           "Shared example groups".
289
290           Example group names are global, but example groups can be defined
291           at any level (i.e. they can be defined in the global context, or
292           inside a "describe" block).
293
294             my $browser;
295             shared_examples_for "all browsers" => sub {
296               it "should open a URL" => sub { ok($browser->open("http://www.google.com/")) };
297               ...
298             };
299             describe "Firefox" => sub {
300               before all => sub { $browser = Firefox->new };
301               it_should_behave_like "all browsers";
302               it "should have firefox features";
303             };
304             describe "Safari" => sub {
305               before all => sub { $browser = Safari->new };
306               it_should_behave_like "all browsers";
307               it "should have safari features";
308             };
309
310       it_should_behave_like DESCRIPTION
311           Asserts that the thing currently being tested passes all the tests
312           in the example group identified by DESCRIPTION (having previously
313           been defined with a "shared_examples_for" block). In essence, this
314           is like copying all the tests from the named "shared_examples_for"
315           block into the current context. See "Shared example groups" and
316           shared_examples_for.
317
318       share %HASH
319           Registers %HASH for sharing data between tests and example groups.
320           This lets you share variables with code in different lexical scopes
321           without resorting to using package (i.e. global) variables or
322           jumping through other hoops to circumvent scope problems.
323
324           Every hash that is "share"d refers to the same data. Sharing a hash
325           will make its existing contents inaccessible, because afterwards it
326           contains the same data that all other shared hashes contain. The
327           result is that you get a hash with global semantics but with
328           lexical scope (assuming %HASH is a lexical variable).
329
330           There are a few benefits of using "share" over using a "regular"
331           global hash. First, you don't have to decide what package the hash
332           will belong to, which is annoying when you have specs in several
333           packages referencing the same shared examples. You also don't have
334           to clutter your examples with colons for fully-qualified names. For
335           example, at my company our specs go in the "ICA::TestCase"
336           hierarchy, and "$ICA::TestCase::Some::Package::variable" is
337           exhausting to both the eyes and the hands. Lastly, using "share"
338           allows "Test::Spec" to provide this functionality without deciding
339           on the variable name for you (and thereby potentially clobbering
340           one of your variables).
341
342             share %vars;      # %vars now refers to the global share
343             share my %vars;   # declare and share %vars in one step
344
345       spec_helper FILESPEC
346           Loads the Perl source in "FILESPEC" into the current spec's
347           package. If "FILESPEC" is relative (no leading slash), it is
348           treated as relative to the spec file (i.e. not the currently
349           running script). This lets you keep helper scripts near the specs
350           they are used by without exercising your File::Spec skills in your
351           specs.
352
353             # in foo/spec.t
354             spec_helper "helper.pl";          # loads foo/helper.pl
355             spec_helper "helpers/helper.pl";  # loads foo/helpers/helper.pl
356             spec_helper "/path/to/helper.pl"; # loads /path/to/helper.pl
357
358   Shared example groups
359       This feature comes straight out of RSpec, as does this documentation:
360
361       You can create shared example groups and include those groups into
362       other groups.
363
364       Suppose you have some behavior that applies to all editions of your
365       product, both large and small.
366
367       First, factor out the "shared" behavior:
368
369         shared_examples_for "all editions" => sub {
370           it "should behave like all editions" => sub {
371             ...
372           };
373         };
374
375       then when you need to define the behavior for the Large and Small
376       editions, reference the shared behavior using the
377       "it_should_behave_like()" function.
378
379         describe "SmallEdition" => sub {
380           it_should_behave_like "all editions";
381         };
382
383         describe "LargeEdition" => sub {
384           it_should_behave_like "all editions";
385           it "should also behave like a large edition" => sub {
386             ...
387           };
388         };
389
390       "it_should_behave_like" will search for an example group by its
391       description string, in this case, "all editions".
392
393       Shared example groups may be included in other shared groups:
394
395         shared_examples_for "All Employees" => sub {
396           it "should be payable" => sub {
397             ...
398           };
399         };
400
401         shared_examples_for "All Managers" => sub {
402           it_should_behave_like "All Employees";
403           it "should be bonusable" => sub {
404             ...
405           };
406         };
407
408         describe Officer => sub {
409           it_should_behave_like "All Managers";
410           it "should be optionable";
411         };
412
413         # generates:
414         ok 1 - Officer should be optionable
415         ok 2 - Officer should be bonusable
416         ok 3 - Officer should be payable
417
418       Refactoring into files
419
420       If you want to factor specs into separate files, variable scopes can be
421       tricky. This is especially true if you follow the recommended pattern
422       and give each spec its own package name. "Test::Spec" offers a couple
423       of functions that ease this process considerably: share and
424       spec_helper.
425
426       Consider the browsers example from "shared_examples_for". A real
427       browser specification would be large, so putting the specs for all
428       browsers in the same file would be a bad idea. So let's say we create
429       "all_browsers.pl" for the shared examples, and give Safari and Firefox
430       "safari.t" and "firefox.t", respectively.
431
432       The problem then becomes: how does the code in "all_browsers.pl" access
433       the $browser variable? In the example code, $browser is a lexical
434       variable that is in scope for all the examples.  But once those
435       examples are split into multiple files, you would have to use either
436       package global variables or worse, come up with some other hack. This
437       is where "share" and "spec_helper" come in.
438
439         # safari.t
440         package Testcase::Safari;
441         use Test::Spec;
442         spec_helper 'all_browsers.pl';
443
444         describe "Safari" => sub {
445           share my %vars;
446           before all => sub { $vars{browser} = Safari->new };
447           it_should_behave_like "all browsers";
448           it "should have safari features";
449         };
450
451         # firefox.t
452         package Testcase::Firefox;
453         use Test::Spec;
454         spec_helper 'all_browsers.pl';
455
456         describe "Firefox" => sub {
457           share my %vars;
458           before all => sub { $vars{browser} = Firefox->new };
459           it_should_behave_like "all browsers";
460           it "should have firefox features";
461         };
462
463         # in all_browsers.pl
464         shared_examples_for "all browsers" => sub {
465           # doesn't have to be the same name!
466           share my %t;
467           it "should open a URL" => sub {
468             ok $t{browser}->open("http://www.google.com/");
469           };
470           ...
471         };
472
473   Order of execution
474       This example, shamelessly adapted from the RSpec website, gives an
475       overview of the order in which examples run, with particular attention
476       to "before" and "after".
477
478         describe Thing => sub {
479           before all => sub {
480             # This is run once and only once, before all of the examples
481             # and before any before("each") blocks.
482           };
483
484           before each => sub {
485             # This is run before each example.
486           };
487
488           before sub {
489             # "each" is the default, so this is the same as before("each")
490           };
491
492           it "should do stuff" => sub {
493             ...
494           };
495
496           it "should do more stuff" => sub {
497             ...
498           };
499
500           after each => sub {
501             # this is run after each example
502           };
503
504           after sub {
505             # "each" is the default, so this is the same as after("each")
506           };
507
508           after all => sub {
509             # this is run once and only once after all of the examples
510             # and after any after("each") blocks
511           };
512
513         };
514

SEE ALSO

516       RSpec <http://rspec.info>, Test::More, Test::Deep, Test::Trap,
517       Test::Builder.
518
519       The mocking and stubbing tools are in Test::Spec::Mocks.
520

AUTHOR

522       Philip Garrett <philip.garrett@icainformatics.com>
523

CONTRIBUTING

525       The source code for Test::Spec lives on github
526       <https://github.com/kingpong/perl-Test-Spec>
527
528       If you want to contribute a patch, fork my repository, make your
529       change, and send me a pull request.
530

SUPPORT

532       If you have found a defect or have a feature request please report an
533       issue at https://github.com/kingpong/perl-Test-Spec/issues. For help
534       using the module, standard Perl support channels like Stack Overflow
535       <http://stackoverflow.com/> and comp.lang.perl.misc
536       <http://groups.google.com/group/comp.lang.perl.misc> are probably your
537       best bet.
538
540       Copyright (c) 2010-2011 by Informatics Corporation of America.
541
542       This program is free software; you can redistribute it and/or modify it
543       under the same terms as Perl itself.
544
545
546
547perl v5.36.0                      2022-07-22                     Test::Spec(3)
Impressum