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