patch

  my $mock = Mock::MonkeyPatch->patch('MyPackage::foo' => sub { ... });
  my $mock = Mock::MonkeyPatch->patch('MyPackage::foo' => sub { ... }, \%options);

Mock a subroutine and return a object to represent it. Takes a fully qualifed subroutine name, a subroutine reference to call in its place, and optionally a hash reference of additional constructor arguments.

The replacement subroutine will be wrapped in a one that will store calling data, then injected in place of the original. Within the replacement subroutine the original is available as the fully qualified subroutine "Mock::MonkeyPatch::ORIGINAL". This can be used to inject behavior before, after, or even around the original. This includes munging the arguments passed to the origial (though the actual arguments are what are stored). For example usage, see "COOKBOOK".

Currently the optional hashref only accepts one option, an initial value for "store_arguments" which is true if not given.

The wrapper will have the same prototype as the mocked function if one exists. The replacement need not have any prototype, the arguments received by the wrapper will be passed to the given sub as they were received. (If this doesn't make any sense to you, don't worry about it.)

arguments

  my $args = $mock->arguments;
  my $args_second_time = $mock->arguments(1);

Returns an array reference containing the arguments that were passed to the mocked subroutine (but see also "store_arguments"). Optionally an integer may be passed which designates the call number to fetch arguments in the same manner of indexing an array (zero indexed). If not given, 0 is assumed, representing the first time the mock was called. Returns "undef" if the mocked subroutine was not called (or was not called enough times).

  use Test::More;
  is_deeply $mock->arguments, [1, 2, 3], 'called with the right arguments';

called

  my $time_called = $mock->called;

Returns the number of times the mocked subroutine was called. This means that that there should be values available from "arguments" up to the value of "$mock->called - 1".

  use Test::More;
  ok $mock->called, 'mock was called';
  is $mock->called, 3, 'mock was called three times';

method_arguments

  my $args = $mock->method_arguments;
  my $args_third_time = $mock->method_arguments(2, 'MyClass');

A wrapper around "arguments" convenient for when the mocked subroutine is called as a method. Like "arguments" it returns a subroutine reference, though it removes the first arguments which is the invocant. It also can take a call number designation.

Additionally it takes a class name to test against the invocant as "$invocant->isa('Class::Name')". If the invocant is not an instance of the class or a subclass thereof it returns "undef".

  use Test::More;
  is_deeply $mock->method_arguments(0, 'FrobberCo::Employee'),
    ['some', 'arguments'], 'mock method called with known arguments on a FrobberCo::Employee instance';

reset

  $mock = $mock->reset;

Reset the historical information stored in the mock, including "arguments" and "called". Returns the mock instance for chaining if desired.

Note that this does not restore the original method. for that, see "restore".

  use Test::More;
  is $mock->called, 3, 'called 3 times';
  is $mock->reset->called, 0, 'called zero times after reset';

restore

  $mock = $mock->restore;

Restore the original method to its original place in the symbol table. This method is also called automatically when the object goes out of scope and is garbage collected. Returns the mock instance for chaining if desired. This method can only be called once!

Note that this does not reset historical information stored in the mock, for that, see "reset".

store_arguments

  $mock = $mock->store_arguments(0);

When true, the default if not passed to the constructor, arguments passed to the mocked subroutine are stored and accessible later via "arguments" and "method_arguments". However sometimes this isn't desirable, especially in cases where the reference count of items in the arguments matter; notably when an object should be destroyed and the destructor's behavior is important. When this is true set "store_arguments" to a false value and only an empty array reference will be stored.

When used as a setter, it returns the mock instance for chaining if desired.

Run code before the original

  my $mock = $self->patch($symbol, sub {
    # do some stuff before the original
    do_mocked_stuff(@_);
    # then call the original function/method
    Mock::MonkeyPatch::ORIGINAL(@_);
  });

Using ORIGINAL in a nonblocking environment

  my $mock = $self->patch($symbol, sub {
    my @args = @_;
    my $orig = \&Mock::MonkeyPatch::ORIGINAL;
    Mojo::IOLoop->timer(1 => sub { $orig->(@args) });
  });