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

SEE ALSO

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

AUTHOR

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

CONTRIBUTING

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

SUPPORT

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