1NAME
2
3 Mock::Quick - Quickly mock objects and classes, even temporarily
4 replace them, side-effect free.
5
6DESCRIPTION
7
8 Mock-Quick is here to solve the current problems with Mocking
9 libraries.
10
11 There are a couple Mocking libraries available on CPAN. The primary
12 problems with these libraries include verbose syntax, and most
13 importantly side-effects. Some Mocking libraries expect you to mock a
14 specific class, and will unload it then redefine it. This is
15 particularly a problem if you only want to override a class on a
16 lexical level.
17
18 Mock-Quick provides a declarative mocking interface that results in a
19 very concise, but clear syntax. There are separate facilities for
20 mocking object instances, and classes. You can quickly create an
21 instance of an object with custom attributes and methods. You can also
22 quickly create an anonymous class, optionally inheriting from another,
23 with whatever methods you desire.
24
25 Mock-Quick also provides a tool that provides an OO interface to
26 overriding methods in existing classes. This tool also allows for the
27 restoration of the original class methods. Best of all this is a
28 localized tool, when your control object falls out of scope the
29 original class is restored.
30
31SYNOPSIS
32
33 MOCKING OBJECTS
34
35 use Mock::Quick;
36
37 my $obj = qobj(
38 foo => 'bar', # define attribute
39 do_it => qmeth { ... }, # define method
40 ...
41 );
42
43 is( $obj->foo, 'bar' );
44 $obj->foo( 'baz' );
45 is( $obj->foo, 'baz' );
46
47 $obj->do_it();
48
49 # define the new attribute automatically
50 $obj->bar( 'xxx' );
51
52 # define a new method on the fly
53 $obj->baz( qmeth { ... });
54
55 # remove an attribute or method
56 $obj->baz( qclear() );
57
58 STRICTER MOCK
59
60 use Mock::Quick;
61
62 my $obj = qstrict(
63 foo => 'bar', # define attribute
64 do_it => qmeth { ... }, # define method
65 ...
66 );
67
68 is( $obj->foo, 'bar' );
69 $obj->foo( 'baz' );
70 is( $obj->foo, 'baz' );
71
72 $obj->do_it();
73
74 # remove an attribute or method
75 $obj->baz( qclear() );
76
77 You can no longer auto-vivify accessors and methods in strict mode:
78
79 # Cannot define the new attribute automatically
80 dies_ok { $obj->bar( 'xxx' ) };
81
82 # Cannot define a new method on the fly
83 dies_ok { $obj->baz( qmeth { ... }) };
84
85 In order to add methods/accessors you need to create a control object.
86
87 CONTROL OBJECTS
88
89 Control objects are objects that let you interface a mocked object.
90 They let you add attributes and methods, or even clear them. This is
91 unnecessary unless you use strict mocking, or choose not to import
92 qmeth() and qclear().
93
94 Take Control
95
96 my $control = qcontrol( $obj );
97
98 Add Attributes
99
100 $control->set_attributes(
101 foo => 'bar',
102 ...
103 );
104
105 Add Methods
106
107 $control->set_methods(
108 do_it => sub { ... }, # No need to use qmeth()
109 ...
110 );
111
112 Clear Attributes/Methods
113
114 $control->clear( qw/foo do_it .../ );
115
116 Toggle strict
117
118 $control->strict( $BOOL );
119
120 Create With Control
121
122 my $obj = qobj ...;
123 my $obj = qstrict ...;
124 my ( $obj, $control ) = qobjc ...;
125 my ( $sobj, $scontrol ) = qstrictc ...;
126
127 MOCKING CLASSES
128
129 Note: the control object returned here is of type Mock::Quick::Class,
130 whereas control objects for qobj style objects are of
131 Mock::Quick::Object::Control.
132
133 IMPLEMENT A CLASS
134
135 This will implement a class at the namespace provided via the
136 -implement argument. The class must not already be loaded. Once
137 complete the real class will be prevented from loading until you call
138 undefine() on the control object.
139
140 use Mock::Quick;
141
142 my $control = qclass(
143 -implement => 'My::Package',
144
145 # Insert a generic new() method (blessed hash)
146 -with_new => 1,
147
148 # Inheritance
149 -subclass => 'Some::Class',
150 # Can also do
151 -subclass => [ 'Class::A', 'Class::B' ],
152
153 # generic get/set attribute methods.
154 -attributes => [ qw/a b c d/ ],
155
156 # Method that simply returns a value.
157 simple => 'value',
158
159 # Custom method.
160 method => sub { ... },
161 );
162
163 my $obj = $control->package->new;
164 # OR
165 my $obj = My::Package->new;
166
167 # Override a method
168 $control->override( foo => sub { ... });
169
170 # Restore it to the original
171 $control->restore( 'foo' );
172
173 # Remove the namespace we created, which would allow the real thing to load
174 # in a require or use statement.
175 $control->undefine();
176
177 You can also use the qimplement() method instead of qclass:
178
179 use Mock::Quick;
180
181 my $control = qimplement 'Some::Package' => ( %args );
182
183 ANONYMOUS MOCKED CLASS
184
185 This is if you just need to generate a class where the package name
186 does not matter. This is done when the -takeover and -implement
187 arguments are both omitted.
188
189 use Mock::Quick;
190
191 my $control = qclass(
192 # Insert a generic new() method (blessed hash)
193 -with_new => 1,
194
195 # Inheritance
196 -subclass => 'Some::Class',
197 # Can also do
198 -subclass => [ 'Class::A', 'Class::B' ],
199
200 # generic get/set attribute methods.
201 -attributes => [ qw/a b c d/ ],
202
203 # Method that simply returns a value.
204 simple => 'value',
205
206 # Custom method.
207 method => sub { ... },
208 );
209
210 my $obj = $control->package->new;
211
212 # Override a method
213 $control->override( foo => sub { ... });
214
215 # Restore it to the original
216 $control->restore( 'foo' );
217
218 # Remove the anonymous namespace we created.
219 $control->undefine();
220
221 TAKING OVER EXISTING/LOADED CLASSES
222
223 use Mock::Quick;
224
225 my $control = qtakeover 'Some::Package' => ( %overrides );
226
227 # Override a method
228 $control->override( foo => sub { ... });
229
230 # Restore it to the original
231 $control->restore( 'foo' );
232
233 # Destroy the control object and completely restore the original class
234 # Some::Package.
235 $control = undef;
236
237 You can also do this through qclass():
238
239 use Mock::Quick;
240
241 my $control = qclass(
242 -takeover => 'Some::Package',
243 %overrides
244 );
245
246METRICS
247
248 All control objects have a 'metrics' method. The metrics method returns
249 a hash where keys are method names, and values are the number of times
250 the method has been called. When a method is altered or removed the key
251 is deleted.
252
253 Metrics only apply to mocked methods. When you takeover an already
254 loaded class metrics will only track overridden methods.
255
256EXPORTS
257
258 Mock-Quick uses Exporter::Declare. This allows for exports to be
259 prefixed or renamed. See "RENAMING IMPORTED ITEMS" in Exporter::Declare
260 for more information.
261
262 $obj = qobj( attribute => value, ... )
263
264 ( $obj, $control ) = qobjc( attribute => value, ... )
265
266 Create an object. Every possible attribute works fine as a get/set
267 accessor. You can define other methods using qmeth {...} and
268 assigning that to an attribute. You can clear a method using qclear()
269 as an argument.
270
271 See Mock::Quick::Object for more.
272
273 $obj = qstrict( attribute => value, ... )
274
275 ( $obj, $control ) = qstrictc( attribute => value, ... )
276
277 Create a stricter object, get/set accessors will not autovivify into
278 existence for undefined attributes.
279
280 $control = qclass( -config => ..., name => $value || sub { ... }, ... )
281
282 Define an anonymous package with the desired methods and
283 specifications.
284
285 See Mock::Quick::Class for more.
286
287 $control = qclass( -takeover => $package, %overrides )
288
289 $control = qtakeover( $package, %overrides );
290
291 Take over an existing class.
292
293 See Mock::Quick::Class for more.
294
295 $control = qimplement( $package, -config => ..., name => $value || sub
296 { ... }, ... )
297
298 $control = qclass( -implement => $package, ... )
299
300 Implement the given package to specifications, altering %INC so that
301 the real class will not load. Destroying the control object will once
302 again allow the original to load.
303
304 qclear()
305
306 Returns a special reference that when used as an argument, will cause
307 Mock::Quick::Object methods to be cleared.
308
309 qmeth { my $self = shift; ... }
310
311 Define a method for an Mock::Quick::Object instance.
312
313 default_export qcontrol => sub { Mock::Quick::Object::Control->new(
314 @_ ) };
315
316AUTHORS
317
318 Chad Granum exodist7@gmail.com
319
320 Ben Hengst notbenh@cpan.org
321
322CONTRIBUTORS
323
324 Contributors are listed as authors in modules they have touched.
325
326 Ben Hengst notbenh@cpan.org
327
328 Glen Hinkle glen@empireenterprises.com
329
330COPYRIGHT
331
332 Copyright (C) 2011 Chad Granum
333
334 Mock-Quick is free software; Standard perl licence.
335
336 Mock-Quick is distributed in the hope that it will be useful, but
337 WITHOUT ANY WARRANTY; without even the implied warranty of
338 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license
339 for more details.
340
341