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 exit()
91 and other hard things like that. "A block eval on steroids."
92 If you specify an import list, only functions directly from
94 "Test::Spec" (those documented below) are available.
95 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 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 runtests unless caller;
109 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 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 "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 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 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 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 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 The output generated is:
160 ok 1 - An unladen swallow has an airspeed of 11 meters per second
162 Contrast this to the following test case to generate the same
164 output:
165 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 "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 context
177 An alias for describe().
178 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 xcontext
186 An alias for xdescribe().
187 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 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 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 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 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 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 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 The default is "each", due to this logic presented in RSpec's
233 documentation:
234 "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 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 (<http://rspec.info/documentation/before_and_after.html>)
249 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 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 "after "all"" blocks run after "after "each"" blocks.
261 around CODE
263 Defines code to be run around tests in the current describe block
264 are run. This code must call "yield"..
265 our $var = 0;
267 describe "Something" => sub {
269 around {
270 local $var = 1;
271 yield;
272 };
273 it "should have localized var" => sub {
275 is $var, 1;
276 };
277 };
278 This CODE will run around each example.
280 yield
282 Runs examples in context of "around" block.
283 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 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 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 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 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 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 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 share %vars; # %vars now refers to the global share
342 share my %vars; # declare and share %vars in one step
343 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 # 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 Shared example groups
358 This feature comes straight out of RSpec, as does this documentation:
359 You can create shared example groups and include those groups into
361 other groups.
362 Suppose you have some behavior that applies to all editions of your
364 product, both large and small.
365 First, factor out the "shared" behavior:
367 shared_examples_for "all editions" => sub {
369 it "should behave like all editions" => sub {
370 ...
371 };
372 };
373 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 describe "SmallEdition" => sub {
379 it_should_behave_like "all editions";
380 };
381 describe "LargeEdition" => sub {
383 it_should_behave_like "all editions";
384 it "should also behave like a large edition" => sub {
385 ...
386 };
387 };
388 "it_should_behave_like" will search for an example group by its
390 description string, in this case, "all editions".
391 Shared example groups may be included in other shared groups:
393 shared_examples_for "All Employees" => sub {
395 it "should be payable" => sub {
396 ...
397 };
398 };
399 shared_examples_for "All Managers" => sub {
401 it_should_behave_like "All Employees";
402 it "should be bonusable" => sub {
403 ...
404 };
405 };
406 describe Officer => sub {
408 it_should_behave_like "All Managers";
409 it "should be optionable";
410 };
411 # generates:
413 ok 1 - Officer should be optionable
414 ok 2 - Officer should be bonusable
415 ok 3 - Officer should be payable
416 Refactoring into files
418 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 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 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 # safari.t
439 package Testcase::Safari;
440 use Test::Spec;
441 spec_helper 'all_browsers.pl';
442 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 # firefox.t
451 package Testcase::Firefox;
452 use Test::Spec;
453 spec_helper 'all_browsers.pl';
454 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 # 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 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 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 before each => sub {
484 # This is run before each example.
485 };
486 before sub {
488 # "each" is the default, so this is the same as before("each")
489 };
490 it "should do stuff" => sub {
492 ...
493 };
494 it "should do more stuff" => sub {
496 ...
497 };
498 after each => sub {
500 # this is run after each example
501 };
502 after sub {
504 # "each" is the default, so this is the same as after("each")
505 };
506 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 };
513
515 RSpec <http://rspec.info>, Test::More, Test::Deep, Test::Trap,
516 Test::Builder.
517 The mocking and stubbing tools are in Test::Spec::Mocks.
519
521 Philip Garrett <philip.garrett@icainformatics.com>
522
524 The source code for Test::Spec lives on github
525 <https://github.com/kingpong/perl-Test-Spec>
526 If you want to contribute a patch, fork my repository, make your
528 change, and send me a pull request.
529
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 This program is free software; you can redistribute it and/or modify it
542 under the same terms as Perl itself.
543perl v5.38.0 2023-07-21 Test::Spec(3)