| 1 |
NAME |
| 2 |
|
| 3 |
Mock::Sub - Mock package, object and standard subroutines, with unit |
| 4 |
testing in mind. |
| 5 |
|
| 6 |
SYNOPSIS |
| 7 |
|
| 8 |
# see EXAMPLES for a full use case and caveats |
| 9 |
|
| 10 |
use Mock::Sub; |
| 11 |
|
| 12 |
# disable warnings about mocking non-existent subs |
| 13 |
|
| 14 |
use Mock::Sub no_warnings => 1 |
| 15 |
|
| 16 |
# create the parent mock object |
| 17 |
|
| 18 |
my $mock = Mock::Sub->new; |
| 19 |
|
| 20 |
# mock some subs... |
| 21 |
|
| 22 |
my $foo = $mock->mock('Package::foo'); |
| 23 |
my $bar = $mock->mock('Package::bar'); |
| 24 |
|
| 25 |
# wait until a mocked sub is called |
| 26 |
|
| 27 |
Package::foo(); |
| 28 |
|
| 29 |
# then... |
| 30 |
|
| 31 |
$foo->name; # name of sub that's mocked |
| 32 |
$foo->called; # was the sub called? |
| 33 |
$foo->called_count; # how many times was it called? |
| 34 |
$foo->called_with; # array of params sent to sub |
| 35 |
|
| 36 |
# have the mocked sub return something when it's called (list or scalar). |
| 37 |
|
| 38 |
$foo->return_value(1, 2, {a => 1}); |
| 39 |
my @return = Package::foo; |
| 40 |
|
| 41 |
# have the mocked sub perform an action |
| 42 |
|
| 43 |
$foo->side_effect( sub { die "eval catch" if @_; } ); |
| 44 |
|
| 45 |
eval { Package::foo(1); }; |
| 46 |
like ($@, qr/eval catch/, "side_effect worked with params"); |
| 47 |
|
| 48 |
# extract the parameters the sub was called with |
| 49 |
|
| 50 |
my @args = $foo->called_with; |
| 51 |
|
| 52 |
# reset the mock object for re-use within the same scope |
| 53 |
|
| 54 |
$foo->reset; |
| 55 |
|
| 56 |
# restore original functionality to the sub |
| 57 |
|
| 58 |
$foo->unmock; |
| 59 |
|
| 60 |
# re-mock a previously unmock()ed sub |
| 61 |
|
| 62 |
$foo->remock; |
| 63 |
|
| 64 |
# check if a sub is mocked |
| 65 |
|
| 66 |
my $state = $foo->mocked_state; |
| 67 |
|
| 68 |
# mock out a CORE:: function. Be warned that this *must* be done within |
| 69 |
# compile stage (BEGIN), and the function can NOT be unmocked prior |
| 70 |
# to the completion of program execution |
| 71 |
|
| 72 |
my ($mock, $caller); |
| 73 |
|
| 74 |
BEGIN { |
| 75 |
$mock = Mock::Sub->new; |
| 76 |
$caller = $mock->mock('caller'); |
| 77 |
}; |
| 78 |
|
| 79 |
$caller->return_value(55); |
| 80 |
caller(); # mocked caller() called |
| 81 |
|
| 82 |
DESCRIPTION |
| 83 |
|
| 84 |
Easy to use and very lightweight module for mocking out sub calls. Very |
| 85 |
useful for testing areas of your own modules where getting coverage may |
| 86 |
be difficult due to nothing to test against, and/or to reduce test run |
| 87 |
time by eliminating the need to call subs that you really don't want or |
| 88 |
need to test. |
| 89 |
|
| 90 |
EXAMPLE |
| 91 |
|
| 92 |
Here's a full example to get further coverage where it's difficult if |
| 93 |
not impossible to test certain areas of your code (eg: you have if/else |
| 94 |
statements, but they don't do anything but call other subs. You don't |
| 95 |
want to test the subs that are called, nor do you want to add |
| 96 |
statements to your code). |
| 97 |
|
| 98 |
Note that if the end subroutine you're testing is NOT Object Oriented |
| 99 |
(and you're importing them into your module that you're testing), you |
| 100 |
have to mock them as part of your own namespace (ie. instead of |
| 101 |
Other::first, you'd mock MyModule::first). |
| 102 |
|
| 103 |
# module you're testing: |
| 104 |
|
| 105 |
package MyPackage; |
| 106 |
|
| 107 |
use Other; |
| 108 |
use Exporter qw(import); |
| 109 |
@EXPORT_OK = qw(test); |
| 110 |
|
| 111 |
my $other = Other->new; |
| 112 |
|
| 113 |
sub test { |
| 114 |
my $arg = shift; |
| 115 |
|
| 116 |
if ($arg == 1){ |
| 117 |
# how do you test this?... there's no return etc. |
| 118 |
$other->first(); |
| 119 |
} |
| 120 |
if ($arg == 2){ |
| 121 |
$other->second(); |
| 122 |
} |
| 123 |
} |
| 124 |
|
| 125 |
# your test file |
| 126 |
|
| 127 |
use MyPackage qw(test); |
| 128 |
use Mock::Sub; |
| 129 |
use Test::More tests => 2; |
| 130 |
|
| 131 |
my $mock = Mock::Sub->new; |
| 132 |
|
| 133 |
my $first = $mock->mock('Other::first'); |
| 134 |
my $second = $mock->mock('Other::second'); |
| 135 |
|
| 136 |
# coverage for first if() in MyPackage::test |
| 137 |
test(1); |
| 138 |
is ($first->called, 1, "1st if() statement covered"); |
| 139 |
|
| 140 |
# coverage for second if() |
| 141 |
test(2); |
| 142 |
is ($second->called, 1, "2nd if() statement covered"); |
| 143 |
|
| 144 |
MOCK OBJECT METHODS |
| 145 |
|
| 146 |
new(%opts) |
| 147 |
|
| 148 |
Instantiates and returns a new Mock::Sub object, ready to be used to |
| 149 |
start creating mocked sub objects. |
| 150 |
|
| 151 |
Optional options: |
| 152 |
|
| 153 |
return_value => $scalar |
| 154 |
|
| 155 |
Set this to have all mocked subs created with this mock object return |
| 156 |
anything you wish (accepts a single scalar only. See return_value() |
| 157 |
method to return a list and for further information). You can also |
| 158 |
set it in individual mocks only (see return_value() method). |
| 159 |
|
| 160 |
side_effect => $cref |
| 161 |
|
| 162 |
Set this in new() to have the side effect passed into all child mocks |
| 163 |
created with this object. See side_effect() method. |
| 164 |
|
| 165 |
mock('sub', %opts) |
| 166 |
|
| 167 |
Instantiates and returns a new mock object on each call. 'sub' is the |
| 168 |
name of the subroutine to mock (requires full package name if the sub |
| 169 |
isn't in main::). |
| 170 |
|
| 171 |
The mocked sub will return undef if a return value isn't set, or a side |
| 172 |
effect doesn't return anything. |
| 173 |
|
| 174 |
Optional parameters: |
| 175 |
|
| 176 |
See new() for a description of the parameters. Both the return_value |
| 177 |
and side_effect parameters can be set in this method to individualize |
| 178 |
each mock object, and will override the global configuration if set in |
| 179 |
new(). |
| 180 |
|
| 181 |
There's also return_value() and side_effect() methods if you want to |
| 182 |
set, change or remove these values after instantiation of a child sub |
| 183 |
object. |
| 184 |
|
| 185 |
mocked_subs |
| 186 |
|
| 187 |
Returns a list of all the names of the subs that are currently mocked |
| 188 |
under the parent mock object. |
| 189 |
|
| 190 |
mocked_objects |
| 191 |
|
| 192 |
Returns a list of all sub objects underneath the parent mock object, |
| 193 |
regardless if its sub is currently mocked or not. |
| 194 |
|
| 195 |
mocked_state('Sub::Name') |
| 196 |
|
| 197 |
Returns 1 if the sub currently under the parent mock object is mocked |
| 198 |
or not, and 0 if not. Croaks if there hasn't been a child sub object |
| 199 |
created with this sub name. |
| 200 |
|
| 201 |
SUB OBJECT METHODS |
| 202 |
|
| 203 |
These methods are for the children mocked sub objects returned from the |
| 204 |
parent mock object. See "MOCK OBJECT METHODS" for methods related to |
| 205 |
the parent mock object. |
| 206 |
|
| 207 |
unmock |
| 208 |
|
| 209 |
Restores the original functionality back to the sub, and runs reset() |
| 210 |
on the object. |
| 211 |
|
| 212 |
remock |
| 213 |
|
| 214 |
Re-mocks the sub within the object after calling unmock on it (accepts |
| 215 |
the side_effect and return_value parameters). |
| 216 |
|
| 217 |
called |
| 218 |
|
| 219 |
Returns true (1) if the sub being mocked has been called, and false (0) |
| 220 |
if not. |
| 221 |
|
| 222 |
called_count |
| 223 |
|
| 224 |
Returns the number of times the mocked sub has been called. |
| 225 |
|
| 226 |
called_with |
| 227 |
|
| 228 |
Returns an array of the parameters sent to the subroutine. confess()s |
| 229 |
if we're called before the mocked sub has been called. |
| 230 |
|
| 231 |
mocked_state |
| 232 |
|
| 233 |
Returns true (1) if the sub the object refers to is currently mocked, |
| 234 |
and false (0) if not. |
| 235 |
|
| 236 |
name |
| 237 |
|
| 238 |
Returns the name of the sub being mocked. |
| 239 |
|
| 240 |
side_effect($cref) |
| 241 |
|
| 242 |
Add (or change/delete) a side effect after instantiation. |
| 243 |
|
| 244 |
Send in a code reference containing an action you'd like the mocked sub |
| 245 |
to perform. |
| 246 |
|
| 247 |
The side effect function will receive all parameters sent into the |
| 248 |
mocked sub. |
| 249 |
|
| 250 |
You can use both side_effect() and return_value() params at the same |
| 251 |
time. side_effect will be run first, and then return_value. Note that |
| 252 |
if side_effect's last expression evaluates to any value whatsoever |
| 253 |
(even false), it will return that and return_value will be skipped. |
| 254 |
|
| 255 |
To work around this and have the side_effect run but still get the |
| 256 |
return_value thereafter, write your cref to evaluate undef as the last |
| 257 |
thing it does: sub { ...; undef; }. |
| 258 |
|
| 259 |
return_value |
| 260 |
|
| 261 |
Add (or change/delete) the mocked sub's return value after |
| 262 |
instantiation. Can be a scalar or list. Send in undef to remove |
| 263 |
previously set values. |
| 264 |
|
| 265 |
reset |
| 266 |
|
| 267 |
Resets the functional parameters (return_value, side_effect), along |
| 268 |
with called() and called_count() back to undef/false. Does not restore |
| 269 |
the sub back to its original state. |
| 270 |
|
| 271 |
NOTES |
| 272 |
|
| 273 |
This module has a backwards parent-child relationship. To use, you |
| 274 |
create a mock object using "PARENT MOCK OBJECT METHODS" new and mock |
| 275 |
methods, thereafter, you use the returned mocked sub object METHODS to |
| 276 |
perform the work. |
| 277 |
|
| 278 |
The parent mock object retains certain information and statistics of |
| 279 |
the child mocked objects (and the subs themselves). |
| 280 |
|
| 281 |
To mock CORE::GLOBAL functions, you *must* initiate within a BEGIN |
| 282 |
block (see SYNOPSIS for details). It is important that if you mock a |
| 283 |
CORE sub, it can't and won't be returned to its original state until |
| 284 |
after the entire program process tree exists. Period. |
| 285 |
|
| 286 |
I didn't make this a Test:: module (although it started that way) |
| 287 |
because I can see more uses than placing it into that category. |
| 288 |
|
| 289 |
AUTHOR |
| 290 |
|
| 291 |
Steve Bertrand, <steveb at cpan.org> |
| 292 |
|
| 293 |
BUGS |
| 294 |
|
| 295 |
Please report any bugs or requests at |
| 296 |
https://github.com/stevieb9/mock-sub/issues |
| 297 |
|
| 298 |
REPOSITORY |
| 299 |
|
| 300 |
https://github.com/stevieb9/mock-sub |
| 301 |
|
| 302 |
BUILD RESULTS |
| 303 |
|
| 304 |
CPAN Testers: http://matrix.cpantesters.org/?dist=Mock-Sub |
| 305 |
|
| 306 |
SUPPORT |
| 307 |
|
| 308 |
You can find documentation for this module with the perldoc command. |
| 309 |
|
| 310 |
perldoc Mock::Sub |
| 311 |
|
| 312 |
ACKNOWLEDGEMENTS |
| 313 |
|
| 314 |
Python's MagicMock module. |
| 315 |
|
| 316 |
LICENSE AND COPYRIGHT |
| 317 |
|
| 318 |
Copyright 2016 Steve Bertrand. |
| 319 |
|
| 320 |
This program is free software; you can redistribute it and/or modify it |
| 321 |
under the terms of either: the GNU General Public License as published |
| 322 |
by the Free Software Foundation; or the Artistic License. |
| 323 |
|
| 324 |
See http://dev.perl.org/licenses/ for more information. |
| 325 |
|