Debian Codegraph @

README

raw
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