.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Spec 3" .TH Test::Spec 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Test::Spec \- Write tests in a declarative specification style .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Test::Spec; # automatically turns on strict and warnings \& \& describe "A date" => sub { \& \& my $date; \& \& describe "in a leap year" => sub { \& \& before each => sub { \& $date = DateTime\->new(year => 2000, month => 2, day => 28); \& }; \& \& it "should know that it is in a leap year" => sub { \& ok($date\->is_leap_year); \& }; \& \& it "should recognize Feb. 29" => sub { \& is($date\->add(days => 1)\->day, 29); \& }; \& \& }; \& \& describe "not in a leap year" => sub { \& before each => sub { \& $date = DateTime\->new(year => 2001, month => 2, day => 28); \& }; \& \& it "should know that it is NOT in a leap year" => sub { \& ok(!$date\->is_leap_year); \& }; \& \& it "should NOT recognize Feb. 29" => sub { \& is($date\->add(days => 1)\->day, 1); \& }; \& }; \& \& }; \& \& runtests unless caller; \& \& # Generates the following output: \& # ok 1 \- A date in a leap year should know that it is in a leap year \& # ok 2 \- A date in a leap year should recognize Feb. 29 \& # ok 3 \- A date not in a leap year should know that it is NOT in a leap year \& # ok 4 \- A date not in a leap year should NOT recognize Feb. 29 \& # 1..4 .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This is a declarative specification-style testing system for behavior-driven development (BDD) in Perl. The tests (a.k.a. examples) are named with strings instead of subroutine names, so your fingers will suffer less fatigue from underscore-itis, with the side benefit that the test reports are more legible. .PP This module is inspired by and borrows heavily from RSpec , a BDD tool for the Ruby programming language. .SS EXPORTS .IX Subsection "EXPORTS" When given \fBno list\fR (i.e. \f(CW\*(C`use Test::Spec;\*(C'\fR), this class will export: .IP \(bu 4 Spec definition functions .Sp These are the functions you will use to define behaviors and run your specs: \&\f(CW\*(C`describe\*(C'\fR, \f(CW\*(C`it\*(C'\fR, \f(CW\*(C`they\*(C'\fR, \f(CW\*(C`before\*(C'\fR, \f(CW\*(C`after\*(C'\fR, \f(CW\*(C`runtests\*(C'\fR, \f(CW\*(C`share\*(C'\fR, \&\f(CW\*(C`shared_examples_for\*(C'\fR, \f(CW\*(C`it_should_behave_like\*(C'\fR, and \f(CW\*(C`spec_helper\*(C'\fR. .IP \(bu 4 The stub/mock functions in Test::Spec::Mocks. .IP \(bu 4 Everything that Test::More normally exports .Sp This includes \f(CW\*(C`ok\*(C'\fR, \f(CW\*(C`is\*(C'\fR and friends. You'll use these to assert correct behavior. .IP \(bu 4 Everything that Test::Deep normally exports .Sp More assertions including \f(CW\*(C`cmp_deeply\*(C'\fR. .IP \(bu 4 Everything that \f(CW\*(C`Test::Trap\*(C'\fR normally exports .Sp The \f(CWtrap()\fR function, which let you test behaviors that call \f(CWexit()\fR and other hard things like that. "A block eval on steroids." .PP If you specify an import list, only functions directly from \f(CW\*(C`Test::Spec\*(C'\fR (those documented below) are available. .SS FUNCTIONS .IX Subsection "FUNCTIONS" .IP runtests 4 .IX Item "runtests" .PD 0 .IP runtests(@patterns) 4 .IX Item "runtests(@patterns)" .PD Runs all the examples whose descriptions match one of the (non case-sensitive) regular expressions in \f(CW@patterns\fR. If \f(CW@patterns\fR is not provided, runs \fIall\fR examples. The environment variable "SPEC" will be used as a default pattern if present. .Sp If called as a function (i.e. \fInot\fR a method call with "\->"), \f(CW\*(C`runtests\*(C'\fR will autodetect the package from which it is called and run that package's examples. A useful idiom is: .Sp .Vb 1 \& runtests unless caller; .Ve .Sp which will run the examples when the file is loaded as a script (for example, by running it from the command line), but not when it is loaded as a module (with \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR). .IP "describe DESCRIPTION => CODE" 4 .IX Item "describe DESCRIPTION => CODE" .PD 0 .IP "describe CODE" 4 .IX Item "describe CODE" .PD Defines a specification context under which examples and more descriptions can be defined. All examples \fImust\fR come inside a \f(CW\*(C`describe\*(C'\fR block. .RS 4 .ie n .IP """describe"" blocks can be nested to DRY up your specs." 4 .el .IP "\f(CWdescribe\fR blocks can be nested to DRY up your specs." 4 .IX Item "describe blocks can be nested to DRY up your specs." For large specifications, \f(CW\*(C`describe\*(C'\fR blocks can save you a lot of duplication: .Sp .Vb 10 \& describe "A User object" => sub { \& my $user; \& before sub { \& $user = User\->new; \& }; \& describe "from a web form" => sub { \& before sub { \& $user\->init_from_tree({ username => "bbill", ... }); \& }; \& it "should read its attributes from the form"; \& describe "when saving" => sub { \& it "should require a unique username"; \& it "should require a password"; \& }; \& }; \& }; .Ve .Sp The setup work done in each \f(CW\*(C`before\*(C'\fR block cascades from one level to the next, so you don't have to make a call to some initialization function manually in each test. It's done automatically based on context. .IP "Using describe blocks improves legibility without requiring more typing." 4 .IX Item "Using describe blocks improves legibility without requiring more typing." The name of the context will be included by default in the success/failure report generated by Test::Builder\-based testing methods (e.g. Test::More's \fBok()\fR function). For an example like this: .Sp .Vb 5 \& describe "An unladen swallow" => sub { \& it "has an airspeed of 11 meters per second" => sub { \& is($swallow\->airspeed, "11m/s"); \& }; \& }; .Ve .Sp The output generated is: .Sp .Vb 1 \& ok 1 \- An unladen swallow has an airspeed of 11 meters per second .Ve .Sp Contrast this to the following test case to generate the same output: .Sp .Vb 4 \& sub unladen_swallow_airspeed : Test { \& is($swallow\->airspeed, "11m/s", \& "An unladen swallow has an airspeed of 11 meters per second"); \& } .Ve .RE .RS 4 .Sp \&\f(CW\*(C`describe\*(C'\fR blocks execute in the order in which they are defined. Multiple \&\f(CW\*(C`describe\*(C'\fR blocks with the same name are allowed. They do not replace each other, rather subsequent \f(CW\*(C`describe\*(C'\fRs extend the existing one of the same name. .RE .IP context 4 .IX Item "context" An alias for \f(CWdescribe()\fR. .IP xdescribe 4 .IX Item "xdescribe" Specification contexts may be disabled by calling \f(CW\*(C`xdescribe\*(C'\fR instead of \&\f(CWdescribe()\fR. All examples inside an \f(CW\*(C`xdescribe\*(C'\fR are reported as "# TODO (disabled)", which prevents Test::Harness/prove from counting them as failures. .IP xcontext 4 .IX Item "xcontext" An alias for \f(CWxdescribe()\fR. .IP "it SPECIFICATION => CODE" 4 .IX Item "it SPECIFICATION => CODE" .PD 0 .IP "it CODE" 4 .IX Item "it CODE" .IP "it TODO_SPECIFICATION" 4 .IX Item "it TODO_SPECIFICATION" .PD Defines an example to be tested. Despite its awkward name, \f(CW\*(C`it\*(C'\fR allows a natural (in my opinion) way to describe expected behavior: .Sp .Vb 6 \& describe "A captive of Buffalo Bill" => sub { \& it "puts the lotion on its skin" => sub { \& ... \& }; \& it "puts the lotion in the basket"; # TODO \& }; .Ve .Sp If a code reference is not passed, the specification is assumed to be unimplemented and will be reported as "TODO (unimplemented)" in the test results (see "todo_skip" in Test::Builder. TODO tests report as skipped, not failed. .IP "they SPECIFICATION => CODE" 4 .IX Item "they SPECIFICATION => CODE" .PD 0 .IP "they CODE" 4 .IX Item "they CODE" .IP "they TODO_SPECIFICATION" 4 .IX Item "they TODO_SPECIFICATION" .PD An alias for "it". This is useful for describing behavior for groups of items, so the verb agrees with the noun: .Sp .Vb 6 \& describe "Captives of Buffalo Bill" => sub { \& they "put the lotion on their skin" => sub { \& ... \& }; \& they "put the lotion in the basket"; # TODO \& }; .Ve .IP xit/xthey 4 .IX Item "xit/xthey" Examples may be disabled by calling \fBxit()\fR/\fBxthey()\fR instead of \fBit()\fR/\fBthey()\fR. These examples are reported as "# TODO (disabled)", which prevents Test::Harness/prove from counting them as failures. .IP "before each => CODE" 4 .IX Item "before each => CODE" .PD 0 .IP "before all => CODE" 4 .IX Item "before all => CODE" .IP "before CODE" 4 .IX Item "before CODE" .PD Defines code to be run before tests in the current describe block are run. If "each" is specified, CODE will be re-executed for every test in the context. If "all" is specified, CODE will only be executed before the first test. .Sp The default is "each", due to this logic presented in RSpec's documentation: .Sp \&\fI"It is very tempting to use before(:all) and after(:all) for situations in which it is not appropriate. before(:all) shares some (not all) state across multiple examples. This means that the examples become bound together, which is an absolute no-no in testing. You should really only ever use before(:all) to set up things that are global collaborators but not the things that you are describing in the examples.\fR .Sp \&\fIThe most common cases of abuse are database access and/or fixture setup. Every example that accesses the database should start with a clean slate, otherwise the examples become brittle and start to lose their value with false negatives and, worse, false positives."\fR .Sp () .Sp There is no restriction on having multiple before blocks. They will run in sequence within their respective "each" or "all" groups. \f(CW\*(C`before "all"\*(C'\fR blocks run before \f(CW\*(C`before "each"\*(C'\fR blocks. .IP "after each => CODE" 4 .IX Item "after each => CODE" .PD 0 .IP "after all => CODE" 4 .IX Item "after all => CODE" .IP "after CODE" 4 .IX Item "after CODE" .PD Like \f(CW\*(C`before\*(C'\fR, but backwards. Runs CODE after each or all tests, respectively. The default is "each". .Sp \&\f(CW\*(C`after "all"\*(C'\fR blocks run \fIafter\fR \f(CW\*(C`after "each"\*(C'\fR blocks. .IP "around CODE" 4 .IX Item "around CODE" Defines code to be run around tests in the current describe block are run. This code must call \f(CW\*(C`yield\*(C'\fR.. .Sp .Vb 1 \& our $var = 0; \& \& describe "Something" => sub { \& around { \& local $var = 1; \& yield; \& }; \& \& it "should have localized var" => sub { \& is $var, 1; \& }; \& }; .Ve .Sp This CODE will run around each example. .IP yield 4 .IX Item "yield" Runs examples in context of \f(CW\*(C`around\*(C'\fR block. .IP "shared_examples_for DESCRIPTION => CODE" 4 .IX Item "shared_examples_for DESCRIPTION => CODE" Defines a group of examples that can later be included in \&\f(CW\*(C`describe\*(C'\fR blocks or other \f(CW\*(C`shared_examples_for\*(C'\fR blocks. See "Shared example groups". .Sp Example group names are \fBglobal\fR, but example groups can be defined at any level (i.e. they can be defined in the global context, or inside a "describe" block). .Sp .Vb 10 \& my $browser; \& shared_examples_for "all browsers" => sub { \& it "should open a URL" => sub { ok($browser\->open("http://www.google.com/")) }; \& ... \& }; \& describe "Firefox" => sub { \& before all => sub { $browser = Firefox\->new }; \& it_should_behave_like "all browsers"; \& it "should have firefox features"; \& }; \& describe "Safari" => sub { \& before all => sub { $browser = Safari\->new }; \& it_should_behave_like "all browsers"; \& it "should have safari features"; \& }; .Ve .IP "it_should_behave_like DESCRIPTION" 4 .IX Item "it_should_behave_like DESCRIPTION" Asserts that the thing currently being tested passes all the tests in the example group identified by DESCRIPTION (having previously been defined with a \f(CW\*(C`shared_examples_for\*(C'\fR block). In essence, this is like copying all the tests from the named \f(CW\*(C`shared_examples_for\*(C'\fR block into the current context. See "Shared example groups" and shared_examples_for. .ie n .IP "share %HASH" 4 .el .IP "share \f(CW%HASH\fR" 4 .IX Item "share %HASH" Registers \f(CW%HASH\fR for sharing data between tests and example groups. This lets you share variables with code in different lexical scopes without resorting to using package (i.e. global) variables or jumping through other hoops to circumvent scope problems. .Sp Every hash that is \f(CW\*(C`share\*(C'\fRd refers to the \fBsame data\fR. Sharing a hash will make its existing contents inaccessible, because afterwards it contains the same data that all other shared hashes contain. The result is that you get a hash with global semantics but with lexical scope (assuming \f(CW%HASH\fR is a lexical variable). .Sp There are a few benefits of using \f(CW\*(C`share\*(C'\fR over using a "regular" global hash. First, you don't have to decide what package the hash will belong to, which is annoying when you have specs in several packages referencing the same shared examples. You also don't have to clutter your examples with colons for fully-qualified names. For example, at my company our specs go in the "ICA::TestCase" hierarchy, and "$ICA::TestCase::Some::Package::variable" is exhausting to both the eyes and the hands. Lastly, using \f(CW\*(C`share\*(C'\fR allows \f(CW\*(C`Test::Spec\*(C'\fR to provide this functionality without deciding on the variable name for you (and thereby potentially clobbering one of your variables). .Sp .Vb 2 \& share %vars; # %vars now refers to the global share \& share my %vars; # declare and share %vars in one step .Ve .IP "spec_helper FILESPEC" 4 .IX Item "spec_helper FILESPEC" Loads the Perl source in \f(CW\*(C`FILESPEC\*(C'\fR into the current spec's package. If \&\f(CW\*(C`FILESPEC\*(C'\fR is relative (no leading slash), it is treated as relative to the spec file (i.e. \fBnot\fR the currently running script). This lets you keep helper scripts near the specs they are used by without exercising your File::Spec skills in your specs. .Sp .Vb 4 \& # in foo/spec.t \& spec_helper "helper.pl"; # loads foo/helper.pl \& spec_helper "helpers/helper.pl"; # loads foo/helpers/helper.pl \& spec_helper "/path/to/helper.pl"; # loads /path/to/helper.pl .Ve .SS "Shared example groups" .IX Subsection "Shared example groups" This feature comes straight out of RSpec, as does this documentation: .PP You can create shared example groups and include those groups into other groups. .PP Suppose you have some behavior that applies to all editions of your product, both large and small. .PP First, factor out the "shared" behavior: .PP .Vb 5 \& shared_examples_for "all editions" => sub { \& it "should behave like all editions" => sub { \& ... \& }; \& }; .Ve .PP then when you need to define the behavior for the Large and Small editions, reference the shared behavior using the \&\f(CWit_should_behave_like()\fR function. .PP .Vb 3 \& describe "SmallEdition" => sub { \& it_should_behave_like "all editions"; \& }; \& \& describe "LargeEdition" => sub { \& it_should_behave_like "all editions"; \& it "should also behave like a large edition" => sub { \& ... \& }; \& }; .Ve .PP \&\f(CW\*(C`it_should_behave_like\*(C'\fR will search for an example group by its description string, in this case, "all editions". .PP Shared example groups may be included in other shared groups: .PP .Vb 5 \& shared_examples_for "All Employees" => sub { \& it "should be payable" => sub { \& ... \& }; \& }; \& \& shared_examples_for "All Managers" => sub { \& it_should_behave_like "All Employees"; \& it "should be bonusable" => sub { \& ... \& }; \& }; \& \& describe Officer => sub { \& it_should_behave_like "All Managers"; \& it "should be optionable"; \& }; \& \& # generates: \& ok 1 \- Officer should be optionable \& ok 2 \- Officer should be bonusable \& ok 3 \- Officer should be payable .Ve .PP \fIRefactoring into files\fR .IX Subsection "Refactoring into files" .PP If you want to factor specs into separate files, variable scopes can be tricky. This is especially true if you follow the recommended pattern and give each spec its own package name. \f(CW\*(C`Test::Spec\*(C'\fR offers a couple of functions that ease this process considerably: share and spec_helper. .PP Consider the browsers example from \f(CW\*(C`shared_examples_for\*(C'\fR. A real browser specification would be large, so putting the specs for all browsers in the same file would be a bad idea. So let's say we create \&\f(CW\*(C`all_browsers.pl\*(C'\fR for the shared examples, and give Safari and Firefox \&\f(CW\*(C`safari.t\*(C'\fR and \f(CW\*(C`firefox.t\*(C'\fR, respectively. .PP The problem then becomes: how does the code in \f(CW\*(C`all_browsers.pl\*(C'\fR access the \f(CW$browser\fR variable? In the example code, \&\f(CW$browser\fR is a lexical variable that is in scope for all the examples. But once those examples are split into multiple files, you would have to use either package global variables or worse, come up with some other hack. This is where \f(CW\*(C`share\*(C'\fR and \f(CW\*(C`spec_helper\*(C'\fR come in. .PP .Vb 4 \& # safari.t \& package Testcase::Safari; \& use Test::Spec; \& spec_helper \*(Aqall_browsers.pl\*(Aq; \& \& describe "Safari" => sub { \& share my %vars; \& before all => sub { $vars{browser} = Safari\->new }; \& it_should_behave_like "all browsers"; \& it "should have safari features"; \& }; \& \& # firefox.t \& package Testcase::Firefox; \& use Test::Spec; \& spec_helper \*(Aqall_browsers.pl\*(Aq; \& \& describe "Firefox" => sub { \& share my %vars; \& before all => sub { $vars{browser} = Firefox\->new }; \& it_should_behave_like "all browsers"; \& it "should have firefox features"; \& }; \& \& # in all_browsers.pl \& shared_examples_for "all browsers" => sub { \& # doesn\*(Aqt have to be the same name! \& share my %t; \& it "should open a URL" => sub { \& ok $t{browser}\->open("http://www.google.com/"); \& }; \& ... \& }; .Ve .SS "Order of execution" .IX Subsection "Order of execution" This example, shamelessly adapted from the RSpec website, gives an overview of the order in which examples run, with particular attention to \f(CW\*(C`before\*(C'\fR and \&\f(CW\*(C`after\*(C'\fR. .PP .Vb 5 \& describe Thing => sub { \& before all => sub { \& # This is run once and only once, before all of the examples \& # and before any before("each") blocks. \& }; \& \& before each => sub { \& # This is run before each example. \& }; \& \& before sub { \& # "each" is the default, so this is the same as before("each") \& }; \& \& it "should do stuff" => sub { \& ... \& }; \& \& it "should do more stuff" => sub { \& ... \& }; \& \& after each => sub { \& # this is run after each example \& }; \& \& after sub { \& # "each" is the default, so this is the same as after("each") \& }; \& \& after all => sub { \& # this is run once and only once after all of the examples \& # and after any after("each") blocks \& }; \& \& }; .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" RSpec , Test::More, Test::Deep, Test::Trap, Test::Builder. .PP The mocking and stubbing tools are in Test::Spec::Mocks. .SH AUTHOR .IX Header "AUTHOR" Philip Garrett .SH CONTRIBUTING .IX Header "CONTRIBUTING" The source code for Test::Spec lives on github .PP If you want to contribute a patch, fork my repository, make your change, and send me a pull request. .SH SUPPORT .IX Header "SUPPORT" If you have found a defect or have a feature request please report an issue at https://github.com/kingpong/perl\-Test\-Spec/issues. For help using the module, standard Perl support channels like Stack Overflow and comp.lang.perl.misc are probably your best bet. .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright (c) 2010\-2011 by Informatics Corporation of America. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.