Provided by: libmock-sub-perl_1.09-2_all 
NAME
Mock::Sub - Mock package, object and standard subroutines, with unit testing in mind.
SYNOPSIS
# see EXAMPLES for a full use case and caveats
use Mock::Sub;
# disable warnings about mocking non-existent subs
use Mock::Sub no_warnings => 1
# create the parent mock object
my $mock = Mock::Sub->new;
# mock some subs...
my $foo = $mock->mock('Package::foo');
my $bar = $mock->mock('Package::bar');
# wait until a mocked sub is called
Package::foo();
# then...
$foo->name; # name of sub that's mocked
$foo->called; # was the sub called?
$foo->called_count; # how many times was it called?
$foo->called_with; # array of params sent to sub
# have the mocked sub return something when it's called (list or scalar).
$foo->return_value(1, 2, {a => 1});
my @return = Package::foo;
# have the mocked sub perform an action
$foo->side_effect( sub { die "eval catch" if @_; } );
eval { Package::foo(1); };
like ($@, qr/eval catch/, "side_effect worked with params");
# extract the parameters the sub was called with (if return_value or
# side_effect is not used, we will return the parameters that were sent into
# the mocked sub (list or scalar context)
my @args = $foo->called_with;
# reset the mock object for re-use within the same scope
$foo->reset;
# restore original functionality to the sub
$foo->unmock;
# re-mock a previously unmock()ed sub
$foo->remock;
# check if a sub is mocked
my $state = $foo->mocked_state;
# mock out a CORE:: function. Be warned that this *must* be done within
# compile stage (BEGIN), and the function can NOT be unmocked prior
# to the completion of program execution
my ($mock, $caller);
BEGIN {
$mock = Mock::Sub->new;
$caller = $mock->mock('caller');
};
$caller->return_value(55);
caller(); # mocked caller() called
DESCRIPTION
Easy to use and very lightweight module for mocking out sub calls. Very useful for
testing areas of your own modules where getting coverage may be difficult due to nothing
to test against, and/or to reduce test run time by eliminating the need to call subs that
you really don't want or need to test.
EXAMPLE
Here's a full example to get further coverage where it's difficult if not impossible to
test certain areas of your code (eg: you have if/else statements, but they don't do
anything but call other subs. You don't want to test the subs that are called, nor do you
want to add statements to your code).
Note that if the end subroutine you're testing is NOT Object Oriented (and you're
importing them into your module that you're testing), you have to mock them as part of
your own namespace (ie. instead of Other::first, you'd mock MyModule::first).
# module you're testing:
package MyPackage;
use Other;
use Exporter qw(import);
@EXPORT_OK = qw(test);
my $other = Other->new;
sub test {
my $arg = shift;
if ($arg == 1){
# how do you test this?... there's no return etc.
$other->first();
}
if ($arg == 2){
$other->second();
}
}
# your test file
use MyPackage qw(test);
use Mock::Sub;
use Test::More tests => 2;
my $mock = Mock::Sub->new;
my $first = $mock->mock('Other::first');
my $second = $mock->mock('Other::second');
# coverage for first if() in MyPackage::test
test(1);
is ($first->called, 1, "1st if() statement covered");
# coverage for second if()
test(2);
is ($second->called, 1, "2nd if() statement covered");
MOCK OBJECT METHODS
"new(%opts)"
Instantiates and returns a new "Mock::Sub" object, ready to be used to start creating
mocked sub objects.
Optional options:
"return_value => $scalar"
Set this to have all mocked subs created with this mock object return anything you
wish (accepts a single scalar only. See "return_value()" method to return a list and
for further information). You can also set it in individual mocks only (see
"return_value()" method).
"side_effect => $cref"
Set this in "new()" to have the side effect passed into all child mocks created with
this object. See "side_effect()" method.
"mock('sub', %opts)"
Instantiates and returns a new mock object on each call. 'sub' is the name of the
subroutine to mock (requires full package name if the sub isn't in "main::").
The mocked sub will return the parameters sent into the mocked sub if a return value isn't
set, or a side effect doesn't return anything, if available. If in scalar context but a
list was sent in, we'll return the first parameter in the list. In list context, we simply
receive the parameters as they were sent in.
Optional parameters:
See "new()" for a description of the parameters. Both the "return_value" and "side_effect"
parameters can be set in this method to individualize each mock object, and will override
the global configuration if set in "new()".
There's also "return_value()" and "side_effect()" methods if you want to set, change or
remove these values after instantiation of a child sub object.
mocked_subs
Returns a list of all the names of the subs that are currently mocked under the parent
mock object.
mocked_objects
Returns a list of all sub objects underneath the parent mock object, regardless if its sub
is currently mocked or not.
mocked_state('Sub::Name')
Returns 1 if the sub currently under the parent mock object is mocked or not, and 0 if
not. Croaks if there hasn't been a child sub object created with this sub name.
SUB OBJECT METHODS
These methods are for the children mocked sub objects returned from the parent mock
object. See "MOCK OBJECT METHODS" for methods related to the parent mock object.
"unmock"
Restores the original functionality back to the sub, and runs "reset()" on the object.
"remock"
Re-mocks the sub within the object after calling "unmock" on it (accepts the side_effect
and return_value parameters).
"called"
Returns true (1) if the sub being mocked has been called, and false (0) if not.
"called_count"
Returns the number of times the mocked sub has been called.
"called_with"
Returns an array of the parameters sent to the subroutine. "confess()s" if we're called
before the mocked sub has been called.
"mocked_state"
Returns true (1) if the sub the object refers to is currently mocked, and false (0) if
not.
"name"
Returns the name of the sub being mocked.
"side_effect($cref)"
Add (or change/delete) a side effect after instantiation.
Send in a code reference containing an action you'd like the mocked sub to perform.
The side effect function will receive all parameters sent into the mocked sub.
You can use both "side_effect()" and "return_value()" params at the same time.
"side_effect" will be run first, and then "return_value". Note that if "side_effect"'s
last expression evaluates to any value whatsoever (even false), it will return that and
"return_value" will be skipped.
To work around this and have the side_effect run but still get the return_value
thereafter, write your cref to evaluate undef as the last thing it does: "sub { ...;
undef; }".
"return_value"
Add (or change/delete) the mocked sub's return value after instantiation. Can be a scalar
or list. Send in "undef" to remove previously set values.
"reset"
Resets the functional parameters ("return_value", "side_effect"), along with "called()"
and "called_count()" back to undef/false. Does not restore the sub back to its original
state.
NOTES
This module has a backwards parent-child relationship. To use, you create a mock object
using "MOCK OBJECT METHODS" "new" and "mock" methods, thereafter, you use the returned
mocked sub object "SUB OBJECT METHODS" to perform the work.
The parent mock object retains certain information and statistics of the child mocked
objects (and the subs themselves).
To mock CORE::GLOBAL functions, you *must* initiate within a "BEGIN" block (see "SYNOPSIS"
for details). It is important that if you mock a CORE sub, it can't and won't be returned
to its original state until after the entire program process tree exists. Period.
I didn't make this a "Test::" module (although it started that way) because I can see more
uses than placing it into that category.
AUTHOR
Steve Bertrand, "<steveb at cpan.org>"
BUGS
Please report any bugs or requests at <https://github.com/stevieb9/mock-sub/issues>
REPOSITORY
<https://github.com/stevieb9/mock-sub>
BUILD RESULTS
CPAN Testers: <http://matrix.cpantesters.org/?dist=Mock-Sub>
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Mock::Sub
ACKNOWLEDGEMENTS
Python's MagicMock module.
LICENSE AND COPYRIGHT
Copyright 2016 Steve Bertrand.
This program is free software; you can redistribute it and/or modify it under the terms of
either: the GNU General Public License as published by the Free Software Foundation; or
the Artistic License.
See <http://dev.perl.org/licenses/> for more information.