view release on metacpan or  search on metacpan

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

=back

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

=head2 FUNCTIONS

=over 4

=item runtests

=item runtests(@patterns)

Runs all the examples whose descriptions match one of the (non case-sensitive)
regular expressions in C<@patterns>. If C<@patterns> is not provided,
runs I<all> examples. The environment variable "SPEC" will be used as a
default pattern if present.

If called as a function (i.e. I<not> a method call with "->"), C<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 C<require> or C<use>).

=item describe DESCRIPTION => CODE

=item describe CODE

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

=over 4

=item C<describe> blocks can be nested to DRY up your specs.

For large specifications, C<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 C<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.

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

=back

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

=item context

An alias for C<describe()>.

=item xdescribe

Specification contexts may be disabled by calling C<xdescribe> instead of
C<describe()>. All examples inside an C<xdescribe> are reported as
"# TODO (disabled)", which prevents Test::Harness/prove from counting them
as failures.

=item xcontext

An alias for C<xdescribe()>.

=item it SPECIFICATION => CODE

=item it CODE

=item it TODO_SPECIFICATION

Defines an example to be tested.  Despite its awkward name, C<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 {