local-lib5/man/man3/Test::MockObject.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Test::MockObject 3"
 132 .TH Test::MockObject 3 "2008-05-27" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Test::MockObject \- Perl extension for emulating troublesome interfaces
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 4
 138 \&  use Test::MockObject;
 139 \&  my $mock = Test::MockObject\->new();
 140 \&  $mock\->set_true( 'somemethod' );
 141 \&  ok( $mock\->somemethod() );
 142 .Ve
 143 .PP
 144 .Vb 3
 145 \&  $mock\->set_true( 'veritas')
 146 \&         \->set_false( 'ficta' )
 147 \&       \->set_series( 'amicae', 'Sunny', 'Kylie', 'Bella' );
 148 .Ve
 149 .SH "DESCRIPTION"
 150 .IX Header "DESCRIPTION"
 151 It's a simple program that doesn't use any other modules, and those are easy to
 152 test.  More often, testing a program completely means faking up input to
 153 another module, trying to coax the right output from something you're not
 154 supposed to be testing anyway.
 155 .PP
 156 Testing is a lot easier when you can control the entire environment.  With
 157 Test::MockObject, you can get a lot closer.
 158 .PP
 159 Test::MockObject allows you to create objects that conform to particular
 160 interfaces with very little code.  You don't have to reimplement the behavior,
 161 just the input and the output.
 162 .Sh "\s-1IMPORTANT\s0 \s-1CAVEAT\s0 \s-1FOR\s0 \s-1TESTERS\s0"
 163 .IX Subsection "IMPORTANT CAVEAT FOR TESTERS"
 164 Please note that it is possible to write highly detailed unit tests that pass
 165 even when your integration tests may fail.  Testing the pieces individually
 166 does not excuse you from testing the whole thing together.  I consider this to
 167 be a feature.
 168 .PP
 169 In cases where you only need to mock one or two pieces of an existing module,
 170 consider Test::MockObject::Extends instead.
 171 .Sh "\s-1EXPORT\s0"
 172 .IX Subsection "EXPORT"
 173 None by default.  Maybe the Test::Builder accessories, in a future version.
 174 .Sh "\s-1FUNCTIONS\s0"
 175 .IX Subsection "FUNCTIONS"
 176 The most important thing a Mock Object can do is to conform sufficiently to an
 177 interface.  For example, if you're testing something that relies on \s-1CGI\s0.pm, you
 178 may find it easier to create a mock object that returns controllable results
 179 at given times than to fake query string input.
 180 .PP
 181 \fIThe Basics\fR
 182 .IX Subsection "The Basics"
 183 .ie n .IP "* ""new""" 4
 184 .el .IP "* \f(CWnew\fR" 4
 185 .IX Item "new"
 186 Creates a new mock object.  By default, this is a blessed hash.  Pass a
 187 reference to bless that reference.
 188 .Sp
 189 .Vb 4
 190 \&    my $mock_array  = Test::MockObject\->new( [] );
 191 \&    my $mock_scalar = Test::MockObject\->new( \e( my $scalar ) );
 192 \&    my $mock_code   = Test::MockObject\->new( sub {} );
 193 \&    my $mock_glob   = Test::MockObject\->new( \e*GLOB );
 194 .Ve
 195 .PP
 196 \fIMocking\fR
 197 .IX Subsection "Mocking"
 198 .PP
 199 Your mock object is nearly useless if you don't tell it what it's mocking.
 200 This is done by installing methods.  You control the output of these mocked
 201 methods.  In addition, any mocked method is tracked.  You can tell not only
 202 what was called, but which arguments were passed.  Please note that you cannot
 203 track non-mocked method calls.  They will still be allowed, though
 204 Test::MockObject will \fIcarp()\fR about them.  This is considered a feature, though
 205 it may be possible to disable this in the future.
 206 .PP
 207 As implied in the example above, it's possible to chain these calls together.
 208 Thanks to a suggestion from the fabulous Piers Cawley (\s-1CPAN\s0 \s-1RT\s0 #1249), this
 209 feature came about in version 0.09.  Shorter testing code is nice!
 210 .ie n .IP "* ""mock(\f(CIname\f(CW, \f(CIcoderef\f(CW)""" 4
 211 .el .IP "* \f(CWmock(\f(CIname\f(CW, \f(CIcoderef\f(CW)\fR" 4
 212 .IX Item "mock(name, coderef)"
 213 Adds a coderef to the object.  This allows code to call the named method on the
 214 object.  For example, this code:
 215 .Sp
 216 .Vb 4
 217 \&    my $mock = Test::MockObject\->new();
 218 \&    $mock\->mock( 'fluorinate',
 219 \&        sub { 'impurifying precious bodily fluids' } );
 220 \&    print $mock\->fluorinate;
 221 .Ve
 222 .Sp
 223 will print a helpful warning message.  Please note that methods are only added
 224 to a single object at a time and not the class.  (There is no small similarity
 225 to the Self programming language or the Class::Prototyped module.)
 226 .Sp
 227 This method forms the basis for most of Test::MockObject's testing goodness.
 228 .Sp
 229 \&\fBPlease Note:\fR this method used to be \f(CW\*(C`add()\*(C'\fR.  Due to its ambiguity, it now
 230 has a different spelling.  For backwards compatibility purposes, \fIadd()\fR is
 231 available, though version 0.07 deprecated it.  It goes to some contortions to
 232 try to do what you mean, but I make few guarantees.
 233 .ie n .IP "* ""fake_module(\fImodule name\f(CW), [ \f(CIsubname\f(CW =""\fR \fIcoderef, ... ]" 4
 234 .el .IP "* \f(CWfake_module(\f(CImodule name\f(CW), [ \f(CIsubname\f(CW =\fR \fIcoderef\fR, ... ]" 4
 235 .IX Item "fake_module(module name), [ subname = coderef, ... ]"
 236 \&\fBNote:\fR this method will likely become a separate module in the near future.
 237 .Sp
 238 Lies to Perl that it has already loaded a named module.  This is handy when
 239 providing a mockup of a real module if you'd like to prevent the actual module
 240 from interfering with the nice fakery.  If you're mocking Regexp::English,
 241 say:
 242 .Sp
 243 .Vb 1
 244 \&    $mock\->fake_module( 'Regexp::English' );
 245 .Ve
 246 .Sp
 247 This is both a class and as an object method.  Beware that this must take place
 248 before the actual module has a chance to load.  Either wrap it in a \s-1BEGIN\s0 block
 249 before a use or require or place it before a \f(CW\*(C`use_ok()\*(C'\fR or \f(CW\*(C`require_ok()\*(C'\fR
 250 call.
 251 .Sp
 252 You can optionally add functions to the mocked module by passing them as name
 253 => coderef pairs to \f(CW\*(C`fake_module()\*(C'\fR.  This is handy if you want to test an
 254 \&\f(CW\*(C`import()\*(C'\fR:
 255 .Sp
 256 .Vb 8
 257 \&    my $import;
 258 \&    $mock\->fake_module(
 259 \&        'Regexp::English',
 260 \&        import => sub { $import = caller }
 261 \&    );
 262 \&    use_ok( 'Regexp::Esperanto' );
 263 \&    is( $import, 'Regexp::Esperanto',
 264 \&        'Regexp::Esperanto should use() Regexp::English' );
 265 .Ve
 266 .Sp
 267 If you use \f(CW\*(C`fake_module()\*(C'\fR to mock a module that already exists in memory \*(--
 268 one you've loaded elsewhere perhaps, but do not pass any subroutines to mock,
 269 this method will throw an exception.  This is because if you call the
 270 constructor later on, you probably won't get a mock object back and you'll be
 271 confused.
 272 .ie n .IP "* ""fake_new(\f(CImodule name\f(CW)""" 4
 273 .el .IP "* \f(CWfake_new(\f(CImodule name\f(CW)\fR" 4
 274 .IX Item "fake_new(module name)"
 275 \&\fBNote:\fR see Test::MockObject::Extends for a better alternative to this
 276 method.
 277 .Sp
 278 Provides a fake constructor for the given module that returns the invoking mock
 279 object.  Used in conjunction with \f(CW\*(C`fake_module()\*(C'\fR, you can force the tested
 280 unit to work with the mock object instead.
 281 .Sp
 282 .Vb 2
 283 \&    $mock\->fake_module( 'CGI' );
 284 \&    $mock\->fake_new( 'CGI' );
 285 .Ve
 286 .Sp
 287 .Vb 4
 288 \&    use_ok( 'Some::Module' );
 289 \&    my $s = Some::Module\->new();
 290 \&    is( $s\->{_cgi}, $mock,
 291 \&        'new() should create and store a new CGI object' );
 292 .Ve
 293 .ie n .IP "* ""set_always(\f(CIname\f(CW, \f(CIvalue\f(CW)""" 4
 294 .el .IP "* \f(CWset_always(\f(CIname\f(CW, \f(CIvalue\f(CW)\fR" 4
 295 .IX Item "set_always(name, value)"
 296 Adds a method of the specified name that always returns the specified value.
 297 .ie n .IP "* ""set_true(\f(CIname_1\f(CW, \f(CIname_2\f(CW, ... \f(CIname_n\f(CW)""" 4
 298 .el .IP "* \f(CWset_true(\f(CIname_1\f(CW, \f(CIname_2\f(CW, ... \f(CIname_n\f(CW)\fR" 4
 299 .IX Item "set_true(name_1, name_2, ... name_n)"
 300 Adds a method of the specified name that always returns a true value.  This can
 301 take a list of names.
 302 .ie n .IP "* ""set_false(\f(CIname_1\f(CW, \f(CIname_2\f(CW, ... \f(CIname_n\f(CW)""" 4
 303 .el .IP "* \f(CWset_false(\f(CIname_1\f(CW, \f(CIname_2\f(CW, ... \f(CIname_n\f(CW)\fR" 4
 304 .IX Item "set_false(name_1, name_2, ... name_n)"
 305 Adds a method of the specified name that always returns a false value.  (Since
 306 it installs an empty subroutine, the value should be false in both scalar and
 307 list contexts.)  This can take a list of names.
 308 .ie n .IP "* ""set_list(\f(CIname\f(CW, [ \f(CIitem1\f(CW, \f(CIitem2\f(CW, ... ]""" 4
 309 .el .IP "* \f(CWset_list(\f(CIname\f(CW, [ \f(CIitem1\f(CW, \f(CIitem2\f(CW, ... ]\fR" 4
 310 .IX Item "set_list(name, [ item1, item2, ... ]"
 311 Adds a method that always returns a given list of values.  It takes some care
 312 to provide a list and not an array, if that's important to you.
 313 .ie n .IP "* ""set_series(\f(CIname\f(CW, [ \f(CIitem1\f(CW, \f(CIitem2\f(CW, ... ]""" 4
 314 .el .IP "* \f(CWset_series(\f(CIname\f(CW, [ \f(CIitem1\f(CW, \f(CIitem2\f(CW, ... ]\fR" 4
 315 .IX Item "set_series(name, [ item1, item2, ... ]"
 316 Adds a method that will return the next item in a series on each call.  This
 317 can help to test error handling, by forcing a failure on the first method call
 318 and then subsequent successes.  Note that the series does not repeat; it will
 319 eventually run out.
 320 .ie n .IP "* ""set_bound(\f(CIname\f(CW, \f(CIreference\f(CW)""" 4
 321 .el .IP "* \f(CWset_bound(\f(CIname\f(CW, \f(CIreference\f(CW)\fR" 4
 322 .IX Item "set_bound(name, reference)"
 323 Adds a method bound to a variable.  Pass in a reference to a variable in your
 324 test.  When you change the variable, the return value of the new method will
 325 change as well.  This is often handier than replacing mock methods.
 326 .ie n .IP "* ""set_isa( \f(CIname1\f(CW, \f(CIname2\f(CW, ... \f(CInamen\f(CW )""" 4
 327 .el .IP "* \f(CWset_isa( \f(CIname1\f(CW, \f(CIname2\f(CW, ... \f(CInamen\f(CW )\fR" 4
 328 .IX Item "set_isa( name1, name2, ... namen )"
 329 Adds an apparent parent to the module, so that calling \f(CW\*(C`isa()\*(C'\fR on the mock
 330 will return true appropriately.  Sometimes you really need this.
 331 .ie n .IP "* ""remove(\f(CIname\f(CW)""" 4
 332 .el .IP "* \f(CWremove(\f(CIname\f(CW)\fR" 4
 333 .IX Item "remove(name)"
 334 Removes a named method.
 335 .PP
 336 \fIChecking Your Mocks\fR
 337 .IX Subsection "Checking Your Mocks"
 338 .ie n .IP "* ""can( $method_name )""" 4
 339 .el .IP "* \f(CWcan( $method_name )\fR" 4
 340 .IX Item "can( $method_name )"
 341 Returns a subroutine reference if this particular mocked object can handle the
 342 named method, false otherwise.
 343 .ie n .IP "* ""isa( $class_name )""" 4
 344 .el .IP "* \f(CWisa( $class_name )\fR" 4
 345 .IX Item "isa( $class_name )"
 346 Returns true if the invocant object mocks a particular class.  You must have
 347 used \f(CW\*(C`set_isa()\*(C'\fR first.
 348 .ie n .IP "* ""called(\f(CIname\f(CW)""" 4
 349 .el .IP "* \f(CWcalled(\f(CIname\f(CW)\fR" 4
 350 .IX Item "called(name)"
 351 Checks to see if something has called a named method on the object.  This
 352 returns a boolean value.  The current implementation does not scale especially
 353 well, so use this sparingly if you need to search through hundreds of calls.
 354 .ie n .IP "* ""clear()""" 4
 355 .el .IP "* \f(CWclear()\fR" 4
 356 .IX Item "clear()"
 357 Clears the internal record of all method calls on the object.  It's handy to do
 358 this every now and then.  Note that this does not affect the mocked methods,
 359 only all of the methods called on the object to this point.
 360 .Sp
 361 It's handy to \f(CW\*(C`clear()\*(C'\fR methods in between series of tests.  That makes it
 362 much easier to call \f(CW\*(C`next_method()\*(C'\fR without having to skip over the calls from
 363 the last set of tests.
 364 .ie n .IP "* ""next_call([ \f(CIposition\f(CW ])""" 4
 365 .el .IP "* \f(CWnext_call([ \f(CIposition\f(CW ])\fR" 4
 366 .IX Item "next_call([ position ])"
 367 Returns the name and argument list of the next mocked method called on an
 368 object, in list context.  In scalar context, returns only the method name.
 369 There are two important things to know about this method.  First, it starts at
 370 the beginning of the call list.  If your code runs like this:
 371 .Sp
 372 .Vb 3
 373 \&    $mock\->set_true( 'foo' );
 374 \&    $mock\->set_true( 'bar' );
 375 \&    $mock\->set_true( 'baz' );
 376 .Ve
 377 .Sp
 378 .Vb 3
 379 \&    $mock\->foo();
 380 \&    $mock\->bar( 3, 4 );
 381 \&    $mock\->foo( 1, 2 );
 382 .Ve
 383 .Sp
 384 Then you might see output of:
 385 .Sp
 386 .Vb 2
 387 \&    my ($name, $args) = $mock\->next_call();
 388 \&    print "$name (@$args)";
 389 .Ve
 390 .Sp
 391 .Vb 1
 392 \&    # prints 'foo'
 393 .Ve
 394 .Sp
 395 .Vb 2
 396 \&    $name = $mock\->next_call();
 397 \&    print $name;
 398 .Ve
 399 .Sp
 400 .Vb 1
 401 \&    # prints 'bar'
 402 .Ve
 403 .Sp
 404 .Vb 2
 405 \&    ($name, $args) = $mock\->next_call();
 406 \&    print "$name (@$args)";
 407 .Ve
 408 .Sp
 409 .Vb 1
 410 \&    # prints 'foo 1 2'
 411 .Ve
 412 .Sp
 413 If you provide an optional number as the \fIposition\fR argument, the method will
 414 skip that many calls, returning the data for the last one skipped.
 415 .Sp
 416 .Vb 3
 417 \&    $mock\->foo();
 418 \&    $mock\->bar();
 419 \&    $mock\->baz();
 420 .Ve
 421 .Sp
 422 .Vb 2
 423 \&    $name = $mock\->next_call();
 424 \&    print $name;
 425 .Ve
 426 .Sp
 427 .Vb 1
 428 \&    # prints 'foo'
 429 .Ve
 430 .Sp
 431 .Vb 2
 432 \&    $name = $mock\->next_call( 2 );
 433 \&    print $name
 434 .Ve
 435 .Sp
 436 .Vb 1
 437 \&    # prints 'baz'
 438 .Ve
 439 .Sp
 440 When it reaches the end of the list, it returns undef.  This is probably the
 441 most convenient method in the whole module, but for the sake of completeness
 442 and backwards compatibility (it takes me a while to reach the truest state of
 443 laziness!), there are several other methods.
 444 .ie n .IP "* ""call_pos(\f(CIposition\f(CW)""" 4
 445 .el .IP "* \f(CWcall_pos(\f(CIposition\f(CW)\fR" 4
 446 .IX Item "call_pos(position)"
 447 Returns the name of the method called on the object at a specified position.
 448 This is handy if you need to test a certain order of calls.  For example:
 449 .Sp
 450 .Vb 5
 451 \&    Some::Function( $mock );
 452 \&    is( $mock\->call_pos(1),  'setup',
 453 \&        'Function() should first call setup()' );
 454 \&    is( $mock\->call_pos(\-1), 'end',
 455 \&        '... and last call end()' );
 456 .Ve
 457 .Sp
 458 Positions can be positive or negative.  Please note that the first position is,
 459 in fact, 1.  (This may change in the future.  I like it, but am willing to
 460 reconsider.)
 461 .ie n .IP "* ""call_args(\f(CIposition\f(CW)""" 4
 462 .el .IP "* \f(CWcall_args(\f(CIposition\f(CW)\fR" 4
 463 .IX Item "call_args(position)"
 464 Returns a list of the arguments provided to the method called at the appropriate
 465 position.  Following the test above, one might say:
 466 .Sp
 467 .Vb 4
 468 \&    is( ($mock\->call_args(1))[0], $mock,
 469 \&        '... passing the object to setup()' );
 470 \&    is( scalar $mock\->call_args(\-1), 0,
 471 \&        '... and no args to end()' );
 472 .Ve
 473 .ie n .IP "* ""call_args_pos(\f(CIcall position\f(CW, \f(CIargument position\f(CW)""" 4
 474 .el .IP "* \f(CWcall_args_pos(\f(CIcall position\f(CW, \f(CIargument position\f(CW)\fR" 4
 475 .IX Item "call_args_pos(call position, argument position)"
 476 Returns the argument at the specified position for the method call at the
 477 specified position.  One might rewrite the first test of the last example as:
 478 .Sp
 479 .Vb 2
 480 \&    is( $mock\->call_args_pos(1, 1), $mock,
 481 \&        '... passing the object to setup()');
 482 .Ve
 483 .ie n .IP "* ""call_args_string(\f(CIposition\f(CW, [ \f(CIseparator\f(CW ])""" 4
 484 .el .IP "* \f(CWcall_args_string(\f(CIposition\f(CW, [ \f(CIseparator\f(CW ])\fR" 4
 485 .IX Item "call_args_string(position, [ separator ])"
 486 Returns a stringified version of the arguments at the specified position.  If
 487 no separator is given, they will not be separated.  This can be used as:
 488 .Sp
 489 .Vb 2
 490 \&    is( $mock\->call_args_string(1), "$mock initialize",
 491 \&        '... passing object, initialize as arguments' );
 492 .Ve
 493 .ie n .IP "* ""called_ok(\f(CImethod name\f(CW, [ \f(CItest name\f(CW ])""" 4
 494 .el .IP "* \f(CWcalled_ok(\f(CImethod name\f(CW, [ \f(CItest name\f(CW ])\fR" 4
 495 .IX Item "called_ok(method name, [ test name ])"
 496 Tests to see whether a method of the specified name has been called on the
 497 object.  This and the following methods use Test::Builder, so they integrate
 498 nicely with a test suite built around Test::Simple, Test::More, or anything
 499 else compatible:
 500 .Sp
 501 .Vb 2
 502 \&    $mock\->foo();
 503 \&    $mock\->called_ok( 'foo' );
 504 .Ve
 505 .Sp
 506 A generic default test name is provided.
 507 .ie n .IP "* ""called_pos_ok(\f(CIposition\f(CW, \f(CImethod name\f(CW, [ \f(CItest name\f(CW ])""" 4
 508 .el .IP "* \f(CWcalled_pos_ok(\f(CIposition\f(CW, \f(CImethod name\f(CW, [ \f(CItest name\f(CW ])\fR" 4
 509 .IX Item "called_pos_ok(position, method name, [ test name ])"
 510 Tests to see whether the named method was called at the specified position.  A
 511 default test name is provided.
 512 .ie n .IP "* ""called_args_pos_is(\f(CImethod position\f(CW, \f(CIargument position\f(CW, \f(CIexpected\f(CW, [ \f(CItest name\f(CW ])""" 4
 513 .el .IP "* \f(CWcalled_args_pos_is(\f(CImethod position\f(CW, \f(CIargument position\f(CW, \f(CIexpected\f(CW, [ \f(CItest name\f(CW ])\fR" 4
 514 .IX Item "called_args_pos_is(method position, argument position, expected, [ test name ])"
 515 Tests to see whether the argument at the appropriate position of the method in
 516 the specified position equals a specified value.  A default, rather
 517 non-descript test name is provided.
 518 .ie n .IP "* ""called_args_string_is(\f(CImethod position\f(CW, \f(CIseparator\f(CW, \f(CIexpected\f(CW, [ \f(CItest name\f(CW ])""" 4
 519 .el .IP "* \f(CWcalled_args_string_is(\f(CImethod position\f(CW, \f(CIseparator\f(CW, \f(CIexpected\f(CW, [ \f(CItest name\f(CW ])\fR" 4
 520 .IX Item "called_args_string_is(method position, separator, expected, [ test name ])"
 521 Joins together all of the arguments to a method at the appropriate position and
 522 matches against a specified string.  A generically bland test name is provided
 523 by default.  You can probably do much better.
 524 .ie n .IP "* ""check_class_loaded( $class_name )""" 4
 525 .el .IP "* \f(CWcheck_class_loaded( $class_name )\fR" 4
 526 .IX Item "check_class_loaded( $class_name )"
 527 Attempts to determine whether you have a class of the given name loaded and
 528 compiled.  Returns true or false.
 529 .PP
 530 \fILogging\fR
 531 .IX Subsection "Logging"
 532 .PP
 533 Test::MockObject logs all mocked methods by default.  Sometimes you don't want
 534 to do this.  To prevent logging all calls to a given method, prepend the name
 535 of the method with \f(CW\*(C`\-\*(C'\fR when mocking it.
 536 .PP
 537 That is:
 538 .PP
 539 .Vb 1
 540 \&    $mock\->set_true( '\-foo', 'bar' );
 541 .Ve
 542 .PP
 543 will set mock both \f(CW\*(C`foo()\*(C'\fR and \f(CW\*(C`bar()\*(C'\fR, causing both to return true.
 544 However, the object will log only calls to \f(CW\*(C`bar()\*(C'\fR, not \f(CW\*(C`foo()\*(C'\fR.  To log
 545 \&\f(CW\*(C`foo()\*(C'\fR again, merely mock it again without the leading \f(CW\*(C`\-\*(C'\fR:
 546 .PP
 547 .Vb 1
 548 \&    $mock\->set_true( 'foo' );
 549 .Ve
 550 .PP
 551 \&\f(CW$mock\fR will log all subsequent calls to \f(CW\*(C`foo()\*(C'\fR again.
 552 .PP
 553 \fISubclassing\fR
 554 .IX Subsection "Subclassing"
 555 .PP
 556 There are two methods provided for subclassing:
 557 .ie n .IP "* ""dispatch_mocked_method( $method_name, @_ )""" 4
 558 .el .IP "* \f(CWdispatch_mocked_method( $method_name, @_ )\fR" 4
 559 .IX Item "dispatch_mocked_method( $method_name, @_ )"
 560 This method determines how to call a method (named as \f(CW$method_name\fR) not
 561 available in this class.  It also controls logging.  You may or may not find it
 562 useful, but I certainly take advantage of it for Test::MockObject::Extends.
 563 .ie n .IP "* ""log_call( $method_name, @_ )""" 4
 564 .el .IP "* \f(CWlog_call( $method_name, @_ )\fR" 4
 565 .IX Item "log_call( $method_name, @_ )"
 566 This method tracks the call of the named method and its arguments.
 567 .SH "TODO"
 568 .IX Header "TODO"
 569 .IP "* Add a factory method to avoid namespace collisions (soon)" 4
 570 .IX Item "Add a factory method to avoid namespace collisions (soon)"
 571 .PD 0
 572 .ie n .IP "* Add more useful methods (catch ""import()""?)" 4
 573 .el .IP "* Add more useful methods (catch \f(CWimport()\fR?)" 4
 574 .IX Item "Add more useful methods (catch import()?)"
 575 .PD
 576 .SH "AUTHOR"
 577 .IX Header "AUTHOR"
 578 chromatic, <chromatic at wgz dot org>
 579 .PP
 580 Thanks go to Curtis 'Ovid' Poe, as well as \s-1ONSITE\s0! Technology, Inc., for
 581 finding several bugs and providing several constructive suggestions.
 582 .PP
 583 Jay Bonci also found a false positive in \f(CW\*(C`called_ok()\*(C'\fR.  Thanks!
 584 .PP
 585 Chris Winters was the first to report I'd accidentally scheduled 0.12 for
 586 deletion without uploading a newer version.  He also gave useful feedback on
 587 Test::MockObject::Extends.
 588 .PP
 589 Stevan Little provided the impetus and code for \f(CW\*(C`set_isa()\*(C'\fR.
 590 .PP
 591 Nicholas Clark found a documentation error.
 592 .PP
 593 Mutant suggested a potential problem with \fIfake_module()\fR.
 594 .SH "SEE ALSO"
 595 .IX Header "SEE ALSO"
 596 perl, Test::Tutorial, Test::More,
 597 <http://www.perl.com/pub/a/2001/12/04/testing.html>,
 598 and
 599 <http://www.perl.com/pub/a/2002/07/10/tmo.html>.
 600 .SH "COPYRIGHT"
 601 .IX Header "COPYRIGHT"
 602 Copyright (c) 2002 \- 2008 by chromatic <chromatic at wgz dot org>.
 603 .PP
 604 This program is free software; you can use, modify, and redistribute it under
 605 the same terms as Perl 5.10.x itself.
 606 .PP
 607 See http://www.perl.com/perl/misc/Artistic.html