1Test::MockObject(3) User Contributed Perl Documentation Test::MockObject(3)
2
6 Test::MockObject - Perl extension for emulating troublesome interfaces
7
9 use Test::MockObject;
10 my $mock = Test::MockObject->new();
11 $mock->set_true( 'somemethod' );
12 ok( $mock->somemethod() );
13 $mock->set_true( 'veritas')
15 ->set_false( 'ficta' )
16 ->set_series( 'amicae', 'Sunny', 'Kylie', 'Bella' );
17
19 It's a simple program that doesn't use any other modules, and those are
20 easy to test. More often, testing a program completely means faking up
21 input to another module, trying to coax the right output from something
22 you're not supposed to be testing anyway.
23 Testing is a lot easier when you can control the entire environment.
25 With Test::MockObject, you can get a lot closer.
26 Test::MockObject allows you to create objects that conform to
28 particular interfaces with very little code. You don't have to
29 reimplement the behavior, just the input and the output.
30 IMPORTANT CAVEATS
32 Before you go wild with your testing powers, consider three caveats:
33 • It is possible to write highly detailed unit tests that pass even
35 when your integration tests may fail. Testing the pieces
36 individually does not excuse you from testing the whole thing
37 together.
38 • In cases where you only need to mock one or two pieces of an
40 existing module, consider Test::MockObject::Extends instead.
41 • If the code under testing produces strange errors about type
43 checks, pass the "-debug" flag when using "Test::MockObject" or
44 "Test::MockObject::Extends". This will load both UNIVERSAL::isa and
45 UNIVERSAL::can to perform additional debugging on the incorrect use
46 of both methods from the UNIVERSAL package. (This behavior used to
47 be active by default, but that was, however correct, probably a
48 burden to onerous for the CPAN.)
49 EXPORT
51 None.
52 METHODS
54 The most important thing a Mock Object can do is to conform
55 sufficiently to an interface. For example, if you're testing something
56 that relies on CGI.pm, you may find it easier to create a mock object
57 that returns controllable results at given times than to fake query
58 string input.
59 The Basics
61 • "new"
63 Creates a new mock object. By default, this is a blessed hash.
65 Pass a reference to bless that reference.
66 my $mock_array = Test::MockObject->new( [] );
68 my $mock_scalar = Test::MockObject->new( \( my $scalar ) );
69 my $mock_code = Test::MockObject->new( sub {} );
70 my $mock_glob = Test::MockObject->new( \*GLOB );
71 Mocking
73 Your mock object is nearly useless if you don't tell it what it's
75 mocking. This is done by installing methods. You control the output
76 of these mocked methods. In addition, any mocked method is tracked.
77 You can tell not only what was called, but which arguments were passed.
78 Please note that you cannot track non-mocked method calls. They will
79 still be allowed, though Test::MockObject will carp() about them. This
80 is considered a feature, though it may be possible to disable this in
81 the future.
82 As implied in the example above, it's possible to chain these calls
84 together. Thanks to a suggestion from the fabulous Piers Cawley (CPAN
85 RT #1249), this feature came about in version 0.09. Shorter testing
86 code is nice!
87 • "mock(name, coderef [, name2, coderef2, ...])"
89 Adds one or more coderefs to the object. This allows code to call
91 the named methods on the object. For example, this code:
92 my $mock = Test::MockObject->new();
94 $mock->mock( 'fluorinate',
95 sub { 'impurifying precious bodily fluids' } );
96 print $mock->fluorinate;
97 will print a helpful warning message. Please note that methods are
99 only added to a single object at a time and not the class. (There
100 is no small similarity to the Self programming language or the
101 Class::Prototyped module.)
102 This method forms the basis for most of Test::MockObject's testing
104 goodness.
105 Please Note: this method used to be add(). Due to its ambiguity,
107 it now has a different spelling. For backwards compatibility
108 purposes, add() is available, though version 0.07 deprecated it.
109 It goes to some contortions to try to do what you mean, but I make
110 few guarantees.
111 • "fake_module(module name), [ subname =" coderef, ... ]
113 Note: See Test::MockModule for an alternate (and better) approach.
115 Lies to Perl that it has already loaded a named module. This is
117 handy when providing a mockup of a real module if you'd like to
118 prevent the actual module from interfering with the nice fakery.
119 If you're mocking Regexp::English, say:
120 $mock->fake_module( 'Regexp::English' );
122 This is both a class and as an object method. Beware that this
124 must take place before the actual module has a chance to load.
125 Either wrap it in a BEGIN block before a use or require or place it
126 before a use_ok() or require_ok() call.
127 You can optionally add functions to the mocked module by passing
129 them as name => coderef pairs to fake_module(). This is handy if
130 you want to test an import():
131 my $import;
133 $mock->fake_module(
134 'Regexp::English',
135 import => sub { $import = caller }
136 );
137 use_ok( 'Regexp::Esperanto' );
138 is( $import, 'Regexp::Esperanto',
139 'Regexp::Esperanto should use() Regexp::English' );
140 If you use fake_module() to mock a module that already exists in
142 memory -- one you've loaded elsewhere perhaps, but do not pass any
143 subroutines to mock, this method will throw an exception. This is
144 because if you call the constructor later on, you probably won't
145 get a mock object back and you'll be confused.
146 • "fake_new(module name)"
148 Note: see Test::MockObject::Extends for a better alternative to
150 this method.
151 Provides a fake constructor for the given module that returns the
153 invoking mock object. Used in conjunction with fake_module(), you
154 can force the tested unit to work with the mock object instead.
155 $mock->fake_module( 'CGI' );
157 $mock->fake_new( 'CGI' );
158 use_ok( 'Some::Module' );
160 my $s = Some::Module->new();
161 is( $s->{_cgi}, $mock,
162 'new() should create and store a new CGI object' );
163 • "set_always(name, value)"
165 Adds a method of the specified name that always returns the
167 specified value.
168 • "set_true(name_1, name_2, ... name_n)"
170 Adds a method of the specified name that always returns a true
172 value. This can take a list of names.
173 • "set_false(name_1, name_2, ... name_n)"
175 Adds a method of the specified name that always returns a false
177 value. (Since it installs an empty subroutine, the value should be
178 false in both scalar and list contexts.) This can take a list of
179 names.
180 • "set_list(name, [ item1, item2, ... ]"
182 Adds a method that always returns a given list of values. It takes
184 some care to provide a list and not an array, if that's important
185 to you.
186 • "set_series(name, [ item1, item2, ... ]"
188 Adds a method that will return the next item in a series on each
190 call. This can help to test error handling, by forcing a failure
191 on the first method call and then subsequent successes. Note that
192 the series does not repeat; it will eventually run out.
193 • "set_bound(name, reference)"
195 Adds a method bound to a variable. Pass in a reference to a
197 variable in your test. When you change the variable, the return
198 value of the new method will change as well. This is often handier
199 than replacing mock methods.
200 • "set_isa( name1, name2, ... namen )"
202 Adds an apparent parent to the module, so that calling isa() on the
204 mock will return true appropriately. Sometimes you really need
205 this.
206 • remove(name)
208 Removes a named method.
210 Checking Your Mocks
212 • can( $method_name )
214 Returns a subroutine reference if this particular mocked object can
216 handle the named method, false otherwise.
217 • isa( $class_name )
219 Returns true if the invocant object mocks a particular class. You
221 must have used set_isa() first.
222 • called(name)
224 Checks to see if something has called a named method on the object.
226 This returns a boolean value. The current implementation does not
227 scale especially well, so use this sparingly if you need to search
228 through hundreds of calls.
229 • clear()
231 Clears the internal record of all method calls on the object. It's
233 handy to do this every now and then. Note that this does not
234 affect the mocked methods, only all of the methods called on the
235 object to this point.
236 It's handy to clear() methods in between series of tests. That
238 makes it much easier to call next_method() without having to skip
239 over the calls from the last set of tests.
240 • "next_call([ position ])"
242 Returns the name and argument list of the next mocked method called
244 on an object, in list context. In scalar context, returns only the
245 method name. There are two important things to know about this
246 method. First, it starts at the beginning of the call list. If
247 your code runs like this:
248 $mock->set_true( 'foo' );
250 $mock->set_true( 'bar' );
251 $mock->set_true( 'baz' );
252 $mock->foo();
254 $mock->bar( 3, 4 );
255 $mock->foo( 1, 2 );
256 Then you might see output of:
258 my ($name, $args) = $mock->next_call();
260 print "$name (@$args)";
261 # prints 'foo'
263 $name = $mock->next_call();
265 print $name;
266 # prints 'bar'
268 ($name, $args) = $mock->next_call();
270 print "$name (@$args)";
271 # prints 'foo 1 2'
273 If you provide an optional number as the position argument, the
275 method will skip that many calls, returning the data for the last
276 one skipped.
277 $mock->foo();
279 $mock->bar();
280 $mock->baz();
281 $name = $mock->next_call();
283 print $name;
284 # prints 'foo'
286 $name = $mock->next_call( 2 );
288 print $name
289 # prints 'baz'
291 When it reaches the end of the list, it returns undef. This is
293 probably the most convenient method in the whole module, but for
294 the sake of completeness and backwards compatibility (it takes me a
295 while to reach the truest state of laziness!), there are several
296 other methods.
297 • call_pos(position)
299 Returns the name of the method called on the object at a specified
301 position. This is handy if you need to test a certain order of
302 calls. For example:
303 Some::Function( $mock );
305 is( $mock->call_pos(1), 'setup',
306 'Function() should first call setup()' );
307 is( $mock->call_pos(-1), 'end',
308 '... and last call end()' );
309 Positions can be positive or negative. Please note that the first
311 position is, in fact, 1. (This may change in the future. I like
312 it, but am willing to reconsider.)
313 • call_args(position)
315 Returns a list of the arguments provided to the method called at
317 the appropriate position. Following the test above, one might say:
318 is( ($mock->call_args(1))[0], $mock,
320 '... passing the object to setup()' );
321 is( scalar $mock->call_args(-1), 0,
322 '... and no args to end()' );
323 • "call_args_pos(call position, argument position)"
325 Returns the argument at the specified position for the method call
327 at the specified position. One might rewrite the first test of the
328 last example as:
329 is( $mock->call_args_pos(1, 1), $mock,
331 '... passing the object to setup()');
332 • "call_args_string(position, [ separator ])"
334 Returns a stringified version of the arguments at the specified
336 position. If no separator is given, they will not be separated.
337 This can be used as:
338 is( $mock->call_args_string(1), "$mock initialize",
340 '... passing object, initialize as arguments' );
341 • "called_ok(method name, [ test name ])"
343 Tests to see whether a method of the specified name has been called
345 on the object. This and the following methods use Test::Builder,
346 so they integrate nicely with a test suite built around
347 Test::Simple, Test::More, or anything else compatible:
348 $mock->foo();
350 $mock->called_ok( 'foo' );
351 A generic default test name is provided.
353 • "called_pos_ok(position, method name, [ test name ])"
355 Tests to see whether the named method was called at the specified
357 position. A default test name is provided.
358 • "called_args_pos_is(method position, argument position, expected, [
360 test name ])"
361 Tests to see whether the argument at the appropriate position of
363 the method in the specified position equals a specified value. A
364 default, rather non-descript test name is provided.
365 • "called_args_string_is(method position, separator, expected, [ test
367 name ])"
368 Joins together all of the arguments to a method at the appropriate
370 position and matches against a specified string. A generically
371 bland test name is provided by default. You can probably do much
372 better.
373 • check_class_loaded( $class_name )
375 Attempts to determine whether you have a class of the given name
377 loaded and compiled. Returns true or false.
378 Logging
380 Test::MockObject logs all mocked methods by default. Sometimes you
382 don't want to do this. To prevent logging all calls to a given method,
383 prepend the name of the method with "-" when mocking it.
384 That is:
386 $mock->set_true( '-foo', 'bar' );
388 will set mock both foo() and bar(), causing both to return true.
390 However, the object will log only calls to bar(), not foo(). To log
391 foo() again, merely mock it again without the leading "-":
392 $mock->set_true( 'foo' );
394 $mock will log all subsequent calls to foo() again.
396 Subclassing
398 There are two methods provided for subclassing:
400 • "dispatch_mocked_method( $method_name, @_ )"
402 This method determines how to call a method (named as $method_name)
404 not available in this class. It also controls logging. You may or
405 may not find it useful, but I certainly take advantage of it for
406 Test::MockObject::Extends.
407 • "log_call( $method_name, @_ )"
409 This method tracks the call of the named method and its arguments.
411
413 • Add a factory method to avoid namespace collisions (soon)
414 • Add more useful methods (catch import()?)
416
418 chromatic, <chromatic at wgz dot org>
419 Thanks go to Curtis 'Ovid' Poe, as well as ONSITE! Technology, Inc.,
421 for finding several bugs and providing several constructive
422 suggestions.
423 Jay Bonci also found a false positive in called_ok(). Thanks!
425 Chris Winters was the first to report I'd accidentally scheduled 0.12
427 for deletion without uploading a newer version. He also gave useful
428 feedback on Test::MockObject::Extends.
429 Stevan Little provided the impetus and code for set_isa().
431 Nicholas Clark found a documentation error.
433 Mutant suggested a potential problem with fake_module().
435
437 perl, Test::Tutorial, Test::More,
438 http://www.perl.com/pub/a/2001/12/04/testing.html, and
439 http://www.perl.com/pub/a/2002/07/10/tmo.html.
440
442 Copyright (c) 2002 - 2016 by chromatic <chromatic at wgz dot org>.
443 This program is free software; you can use, modify, and redistribute it
445 under the same terms as Perl 5.24 itself.
446 See http://www.perl.com/perl/misc/Artistic.html
448perl v5.38.0 2023-07-21 Test::MockObject(3)