/ 
Test-Spec-0.30
River stage two • 54 direct dependents • 65 total dependents
/ Test::Spec

NAME

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

SYNOPSIS

use Test::Spec;

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

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.

This module is inspired by and borrows heavily from RSpec (http://rspec.info/documentation/), a BDD tool for the Ruby programming language.

EXPORTS

When given no list (i.e. use Test::Spec;), this class will export:

  • describe, it, before, after, and runtests

    These are the functions you will use to define behaviors and run your specs.

  • The stub/mock functions in Test::Spec::Mocks.

  • Everything that Test::More normally exports

    This includes ok, is and friends. You'll use these to assert correct behavior.

  • Everything that Test::Deep normally exports

    More assertions including cmp_deeply.

  • Everything that Test::Trap normally exports

    The trap() function, which let you test behaviors that call exit() and other hard things like that. "A block eval on steroids."

If you specify an import list, only functions directly from Test::Spec (those documented below) are available.

FUNCTIONS

runtests
runtests(@patterns)

Runs all the examples whose descriptions match one of the regular expressions in @patterns. If @patterns is not provided, runs all examples. The environment variable "SPEC" will be used as a default pattern if present.

If called as a function (i.e. not a method call with "->"), runtests will autodetect the package from which it is called and run that package's examples. A useful idiom is:

runtests unless caller;

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 require or use).

describe DESCRIPTION => CODE
describe CODE

Defines a specification context under which examples and more descriptions can be defined. All examples must come inside a describe block.

describe blocks can be nested to DRY up your specs.

For large specifications, describe blocks can save you a lot of duplication:

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";
    };
  };
};

The setup work done in each before 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.

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 ok() function). For an example like this:

describe "An unladen swallow" => sub {
  it "has an airspeed of 11 meters per second" => sub {
    is($swallow->airspeed, "11m/s");
  };
};

The output generated is:

ok 1 - An unladen swallow has an airspeed of 11 meters per second

Contrast this to the following test case to generate the same output:

sub unladen_swallow_airspeed : Test {
  is($swallow->airspeed, "11m/s",
     "An unladen swallow has an airspeed of 11 meters per second");
}

describe blocks execute in the order in which they are defined. Multiple describe blocks with the same name are allowed. They do not replace each other, rather subsequent describes extend the existing one of the same name.

it SPECIFICATION => CODE
it CODE
it TODO_SPECIFICATION

Defines an example to be tested. Despite its awkward name, it allows a natural (in my opinion) way to describe expected behavior:

describe "A captive of Buffalo Bill" => sub {
  it "puts the lotion on its skin" => sub {
    ...
  };
  it "puts the lotion in the basket"; # TODO
};

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.

they SPECIFICATION => CODE
they CODE
TODO_SPECIFICATION

An alias for "it". This is useful for describing behavior for groups of items, so the verb agrees with the noun:

describe "Captives of Buffalo Bill" => sub {
  they "put the lotion on their skin" => sub {
    ...
  };
  they "put the lotion in the basket"; # TODO
};
before each => CODE
before all => CODE
before CODE

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.

The default is "each", due to this logic presented in RSpec's documentation:

"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.

The 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."

(http://rspec.info/documentation/before_and_after.html)

There is no restriction on having multiple before blocks. They will run in sequence within their respective "each" or "all" groups. before "all" blocks run before before "each" blocks.

after each => CODE
after all => CODE
after CODE

Like before, but backwards. Runs CODE after each or all tests, respectively. The default is "each".

after "all" blocks run after after "each" blocks.

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 before and after.

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
  };

};

SEE ALSO

RSpec (http://rspec.info), Test::More, Test::Deep, Test::Trap, Test::Builder.

The mocking and stubbing tools are in Test::Spec::Mocks.

AUTHOR

Philip Garrett <philip.garrett@icainformatics.com>

CONTRIBUTING

The source code for Test::Spec lives on github: https://github.com/kingpong/perl-Test-Spec

If you want to contribute a patch, fork my repository, make your change, and send me a pull request.

COPYRIGHT & LICENSE

Copyright (c) 2010 by Informatics Corporation of America.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.