1Test::Spec(3) User Contributed Perl Documentation Test::Spec(3)
2
6 Test::Spec - Write tests in a declarative specification style
7
9 use Test::Spec; # automatically turns on strict and warnings
10 describe "A date" => sub {
12 my $date;
14 describe "in a leap year" => sub {
16 before each => sub {
18 $date = DateTime->new(year => 2000, month => 2, day => 28);
19 };
20 it "should know that it is in a leap year" => sub {
22 ok($date->is_leap_year);
23 };
24 it "should recognize Feb. 29" => sub {
26 is($date->add(days => 1)->day, 29);
27 };
28 };
30 describe "not in a leap year" => sub {
32 before each => sub {
33 $date = DateTime->new(year => 2001, month => 2, day => 28);
34 };
35 it "should know that it is NOT in a leap year" => sub {
37 ok(!$date->is_leap_year);
38 };
39 it "should NOT recognize Feb. 29" => sub {
41 is($date->add(days => 1)->day, 1);
42 };
43 };
44 };
46 runtests unless caller;
48 # 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
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 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 EXPORTS
68 When given no list (i.e. "use Test::Spec;"), this class will export:
69 • Spec definition functions
71 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 • The stub/mock functions in Test::Spec::Mocks.
78 • Everything that Test::More normally exports
80 This includes "ok", "is" and friends. You'll use these to assert
82 correct behavior.
83 • Everything that Test::Deep normally exports
85 More assertions including "cmp_deeply".
87 • Everything that "Test::Trap" normally exports
89 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 If you specify an import list, only functions directly from
95 "Test::Spec" (those documented below) are available.
96 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 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 runtests unless caller;
110 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 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 "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 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 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 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 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 The output generated is:
161 ok 1 - An unladen swallow has an airspeed of 11 meters per second
163 Contrast this to the following test case to generate the same
165 output:
166 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 "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 context
178 An alias for "describe()".
179 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 xcontext
187 An alias for "xdescribe()".
188 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 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 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 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 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 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 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 The default is "each", due to this logic presented in RSpec's
234 documentation:
235 "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 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 (<http://rspec.info/documentation/before_and_after.html>)
250 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 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 "after "all"" blocks run after "after "each"" blocks.
262 around CODE
264 Defines code to be run around tests in the current describe block
265 are run. This code must call "yield"..
266 our $var = 0;
268 describe "Something" => sub {
270 around {
271 local $var = 1;
272 yield;
273 };
274 it "should have localized var" => sub {
276 is $var, 1;
277 };
278 };
279 This CODE will run around each example.
281 yield
283 Runs examples in context of "around" block.
284 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 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 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 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 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 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 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 share %vars; # %vars now refers to the global share
343 share my %vars; # declare and share %vars in one step
344 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 # 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 Shared example groups
359 This feature comes straight out of RSpec, as does this documentation:
360 You can create shared example groups and include those groups into
362 other groups.
363 Suppose you have some behavior that applies to all editions of your
365 product, both large and small.
366 First, factor out the "shared" behavior:
368 shared_examples_for "all editions" => sub {
370 it "should behave like all editions" => sub {
371 ...
372 };
373 };
374 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 describe "SmallEdition" => sub {
380 it_should_behave_like "all editions";
381 };
382 describe "LargeEdition" => sub {
384 it_should_behave_like "all editions";
385 it "should also behave like a large edition" => sub {
386 ...
387 };
388 };
389 "it_should_behave_like" will search for an example group by its
391 description string, in this case, "all editions".
392 Shared example groups may be included in other shared groups:
394 shared_examples_for "All Employees" => sub {
396 it "should be payable" => sub {
397 ...
398 };
399 };
400 shared_examples_for "All Managers" => sub {
402 it_should_behave_like "All Employees";
403 it "should be bonusable" => sub {
404 ...
405 };
406 };
407 describe Officer => sub {
409 it_should_behave_like "All Managers";
410 it "should be optionable";
411 };
412 # generates:
414 ok 1 - Officer should be optionable
415 ok 2 - Officer should be bonusable
416 ok 3 - Officer should be payable
417 Refactoring into files
419 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 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 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 # safari.t
440 package Testcase::Safari;
441 use Test::Spec;
442 spec_helper 'all_browsers.pl';
443 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 # firefox.t
452 package Testcase::Firefox;
453 use Test::Spec;
454 spec_helper 'all_browsers.pl';
455 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 # 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 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 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 before each => sub {
485 # This is run before each example.
486 };
487 before sub {
489 # "each" is the default, so this is the same as before("each")
490 };
491 it "should do stuff" => sub {
493 ...
494 };
495 it "should do more stuff" => sub {
497 ...
498 };
499 after each => sub {
501 # this is run after each example
502 };
503 after sub {
505 # "each" is the default, so this is the same as after("each")
506 };
507 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 };
514
516 RSpec <http://rspec.info>, Test::More, Test::Deep, Test::Trap,
517 Test::Builder.
518 The mocking and stubbing tools are in Test::Spec::Mocks.
520
522 Philip Garrett <philip.garrett@icainformatics.com>
523
525 The source code for Test::Spec lives on github
526 <https://github.com/kingpong/perl-Test-Spec>
527 If you want to contribute a patch, fork my repository, make your
529 change, and send me a pull request.
530
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 This program is free software; you can redistribute it and/or modify it
543 under the same terms as Perl itself.
544perl v5.36.0 2022-07-22 Test::Spec(3)