view release on metacpan or  search on metacpan

local/lib/perl5/Test/Spec.pm  view on Meta::CPAN

  shared_examples_for "all editions" => sub {
    it "should behave like all editions" => sub {
      ...
    };
  };

then when you need to define the behavior for the Large and Small
editions, reference the shared behavior using the
C<it_should_behave_like()> function.

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

C<it_should_behave_like> will search for an example group by its
description string, in this case, "all editions".

Shared example groups may be included in other shared groups:

  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

=head3 Refactoring into files

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. C<Test::Spec> offers a couple
of functions that ease this process considerably: L<share|/share %HASH>
and L<spec_helper|/spec_helper FILESPEC>.

Consider the browsers example from C<shared_examples_for>. 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
C<all_browsers.pl> for the shared examples, and give Safari and Firefox
C<safari.t> and C<firefox.t>, respectively.

The problem then becomes: how does the code in C<all_browsers.pl> access
the C<$browser> variable? In L<the example code|/shared_examples_for DESCRIPTION =E<gt> CODE>,
C<$browser> 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 C<share> and C<spec_helper> come in.

  # safari.t
  package Testcase::Safari;
  use Test::Spec;
  spec_helper 'all_browsers.pl';

  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 'all_browsers.pl';

  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't have to be the same name!
    share my %t;
    it "should open a URL" => sub {
      ok $t{browser}->open("http://www.google.com/");
    };
    ...
  };

=head2 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 C<before> and
C<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.
    };