view release on metacpan or  search on metacpan

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

C<$method_name>/C<$result> pairs or a reference to a hash containing the same.
Each C<$method_name> listed is stubbed to return the associated value
(C<$result>); or if the value is a subroutine reference, it is stubbed
in-place (the subroutine becomes the method).

Examples:

  # A blank object with no methods.
  # Gives a true response to ref() and blessed().
  my $blank = stub();

  # Static responses to width() and height():
  my $rect = stub(width => 5, height => 5);

  # Dynamic response to area():
  my $radius = 1.0;
  my $circle_stub = stub(area => sub { PI * $radius * $radius });

You can also stub more methods, just like with any other object:

  my $rect = stub(width => 5, height => 5);
  $rect->stubs(area => sub { my $self = shift; $self->width * $self->height });


=item $thing->stubs($method_name)

=item $thing->stubs($method_name => $result)

=item $thing->stubs($method_name => sub { $result })

=item $thing->stubs({ $method_name => $result })

Stubs one or more methods on an existing class or instance, C<$thing>.

If passed only one (non-hash) argument, it is interpreted as a method name.
The return value of the stubbed method will be C<undef>.

Otherwise, the arguments are a list of C<$method_name> and C<$result>
pairs, either as a flat list or as a hash reference. Each method is
installed onto C<$thing>, and returns the specified result. If the result is a
subroutine reference, it will be called for every invocation of the method.


=item mock()

Returns a new blank, anonymous mock object, suitable for mocking methods with
L<expects()|/"$thing-E<gt>expects($method)">.

  my $rect = mock();
  $rect->expects('area')->returns(100);


=item $thing->expects($method)

Installs a mock method named C<$method> onto the class or object C<$thing> and
returns an Test::Spec::Mocks::Expectation object, which you can use to set the
return value with C<returns()> and other expectations. By default, the method
is expected to be called L<at_least_once>.

If the expectation is not met before the enclosing example completes, the
mocked method will raise an exception that looks something like:

  expected foo to be called exactly 1 time, but it was called 0 times

=back

=head1 EXPECTATION ADJUSTMENT METHODS

These are methods of the Test::Spec::Mocks::Expectation class, which you'll
receive by calling C<expects()> on a class or object instance.

=over 4

=item returns( $result )

=item returns( @result )

=item returns( \&callback )

Configures the mocked method to return the specified result when called. If
passed a subroutine reference, the subroutine will be executed when the method
is called, and the result is the return value.

  $rect->expects('height')->returns(5);
  # $rect->height ==> 5

  @points = ( [0,0], [1,0], [1,1], [1,0] );
  $rect->expects('points')->returns(@points);
  # (@p = $rect->points) ==> ( [0,0], [1,0], [1,1], [1,0] )
  # ($p = $rect->points) ==> 4

  @points = ( [0,0], [1,0], [1,1], [1,0] );
  $rect->expects('next_point')->returns(sub { shift @points });
  # $rect->next_point ==> [0,0]
  # $rect->next_point ==> [1,0]
  # ...

=item exactly($N)

Configures the mocked method so that it must be called exactly $N times. 

=item never

Configures the mocked method so that it must never be called.

=item once

Configures the mocked method so that it must be called exactly one time.

=item at_least($N)

Configures the mocked method so that it must be called at least $N times.

=item at_least_once

Configures the mocked method so that it must be called at least 1 time.
This is just syntactic sugar for C<at_least(1)>.

=item at_most($N)

Configures the mocked method so that it must be called no more than $N times.