Provided by: libtest-mockclass-perl_1.04-3_all bug

NAME

       Test::MockClass - A module to provide mock classes and mock objects for testing

SYNOPSIS

           # Pass in the class name and version that you want to mock
           use Test::MockClass qw{ClassToMock 1.1};

           # create a MockClass object to handle a specific class
           my $mockClass = Test::MockClass->new('ClassToMock');

           # specify to inherit from a real class, or a mocked class:
           $mockClass->inheritFrom('IO::Socket');

           # make a constructor for the class, can also use 'addMethod' for more control
           $mockClass->defaultConstructor(%classWideDefaults);

           # add a method:
           $mockClass->addMethod('methodname', $coderef);

           # add a simpler method, and specify return values that it will return automatically
           $mockClass->setReturnValues('methodname2', 'always', 3);

           # create an instance of the mocked class:
           my $mockObject = $mockClass->create(%instanceData);

           # set the desired call order for the methods:
           $mockClass->setCallOrder('methodname2', 'methodname', 'methodname');

           # run tests using the mock Class elsewhere:
           #:in the class to test:
           sub objectFactory {
               return ClassToMock->new;
           }
           #:in your test code:
               assert($testObj->objectFactory->isa("ClassToMock"));

           # get the object Id for the rest of the methods:
           my $objectId = "$mockObject";
           #or
           $objectId = $mockClass->getNextObjectId();

           # verify that the methods were called in the correct order:
           if($mockClass->verifyCallOrder($objectId)) {
               # do something
           }

           # get the order that the methods were called:
           my @calls = $mockClass->getCallOrder($objectId);

           # get the list of arguments passed per call:
           my @argList = $mockClass->getArgumentList($objectId, 'methodname', $callPosition);

           # get the list of accesses made to a particular attribute (hashkey in $mockObject)
           my @accesses = $mockClass->getAttributeAccess($objectId, 'attribute');

EXPORTS

       Nothing by default.

REQUIRES

       The Hook::WrapSub manpage, the Tie::Watch manpage, the Scalar::Util manpage.

DESCRIPTION

       This module provides a simple interface for creating mock classes and mock objects with
       mock methods for mock purposes, I mean testing purposes.  It also provides a simple
       mechanism for tracking the interactions to the mocked objects.  I originally wrote this
       class to help me test object factory methods, since then, I've added some more features.
       This module is hopefully going to be the Date::Manip of mock class/object creation, so
       email me with lots of ideas, everything but the kitchen sink will go in!

METHODS

   import
       This method is called when you use the class.  It optionally takes a list of classes to
       mock:

         use Test::MockClass qw{IO::Socket File::Finder DBI};

       You can also specify the version numbers for the classes:

         use Test::MockClass qw{DBD::mysql 1.1 Apache::Cookie 1.2.1}

       This use fools perl into thinking that the class/module is already loaded, so it will
       override any use statement within the code that you're trying to test.

   new
       The Test::MockClass constructor.  It has one required argument which is the name of the
       class to mock.  It also optionally takes a version number as a second argument (this
       version will override any passed to the use statement).  It returns a Test::MockClass
       object, which is the interface for all of the method making and tracking for mock objects
       created later.

           my $mockClass = Test::MockClass->new('ClassToMock', '1.1');

       If no version is specified in either the use statement or the call to new, it defaults to
       -1.

   addMethod
       A mocked class needs methods, and this is the most flexible way to create them.  It has
       two required arguments, the first one is the name of the method to mock.   The second
       argument is a coderef to use as the contents of the mocked method.  It returns nothing of
       value.  What it does that is valuable is install the method into the symbol table of the
       mocked class.

           $mockClass->addMethod('new', sub { my $proto = shift; my $class = ref($proto) || $proto; my $self = {}; bless($self, $class); });

           $mockClass->addMethod('foo', sub {return 'foo';});

   defaultConstructor
       I'm often too lazy, or, er, busy to write my own mocked constructor, especially when the
       constructor is a simple standard one.  For those times I use the defaultConstructor
       method.  This method takes a hashy list as the optional arguments, which it passes to the
       constructor as class-wide default attributes/values.  It installs the constructor in the
       mocked class as 'new' or whatever was set with $mockClass->constructor() (see that method
       description later in this document).

           $mockClass->defaultConstructor('cat' => 'hat', 'grinch' => 'x-mas');

       Of course, this assumes that your objects are based on hashes.

   setReturnValues
       My laziness often extends beyond the simple constructor to the methods of the mocked class
       themselves.  Often I don't feel like writing a whole method when all I need for testing is
       to have the mocked method return a specific value.  For times like this I'm glad I wrote
       the setReturnValues method.  This method takes a variable number of arguments, but the
       first two are required.  The first argument is the name of the method to mock.  The second
       argument specifies what the mocked method will return.  Any additional arguments may be
       used as return values depending on the type of the second argument.  The possible values
       for the second argument are as follows:

       true
           This specifies that the method should always return true (1).

             $mockClass->setReturnValues('trueMethod', 'true');
             if($mockObject->trueMethod) {}

       false
           This specifies that the method should always return false (0).

             $mockClass->setReturnValues('falseMethod', 'false');
             unless($mockObject->falseMethod) {}

       undef
           This specifies that the method should always return undef.

             $mockClass->setReturnValues('undefMethod', 'undef');
             if(defined $mockObject->undefMethod) {}

       always
           This specifies that the method should always return all of the rest of the arguments
           to setReturnValues.

             $mockClass->setReturnValues('alwaysFoo', 'always', 'foo');
             $mockClass->setReturnValues('alwaysFooNBar', 'always', 'foo', 'bar');

       series
           This specifies that the method should return 1 each of the rest of the arguments per
           method invocation until the arguments have all been used, then it returns undef.

             $mockClass->setReturnValues('aFewGoodMen', 'series', 'Abraham', 'Martin', 'John');

       cycle
           This specifies that the method should return 1 each of the rest of the arguments per
           method invocation, once all have been used it starts over at the beginning.

             $mockClass->setReturnValues('boybands', 'cycle', 'BackAlley-Bros', 'OutOfSync', 'OldKidsOverThere');

       random
           This specifies that the method should return a random value from the list.  Well, as
           random as perl's srand/rand can get it anyway.

             $mockClass->setReturnValues('userInput', 'random', (0..9));

   setCallOrder
       Sometimes it's important to impose some guidelines for behavior on your mocked objects.
       This method allows you to set the desired call order for your mocked methods, the order
       that you want them to be called.  It takes a variable length list which is the names of
       the methods in the proper order.  This list is then used in comparison with the actual
       call order made on individual mocked objects.

           $mockClass->setCallOrder('new', 'foo', 'bas', 'bar', 'foo');

   getCallOrder
       Objects often do bizzare and unnatural things when you aren't looking, so I wrote this
       method to track what they did behind the scenes.  This method returns the actual method
       call order for a given object.  It takes one required argument which is the object Id for
       the object you want the call order of.  One way to get an object's Id is to simply pass it
       in stringified:

           my @callOrder = $mockClass->getCallOrder("$mockObject");

       This method returns an array in list context and an arrayref under scalar context.  It
       returns nothing under void context.

   verifyCallOrder
       Now we could compare, by hand, the differences between the call order we wanted and the
       call order we got, but that would be all boring and we've got better things to do.  I say
       we just use the verifyCallOrder method and be done with it.  This method takes one
       required argument which is the object Id of the object we want to verify.  It returns true
       or false depending on whether the methods were called in the correct order or not,
       respectively.

           if($mockClass->verifyCallOrder("$mockObject")) {
              # do something
           }

   create
       Sometimes you might want to use the Test::MockClass object to actually return mocked
       objects itself, I'm not sure why, but maybe someone would want it, so for them there is
       the create method.  This method takes a variable sized hashy list which will be used as
       instance attributes/values.  These attributes will ovverride any class-wide defaults set
       by the defaultConstructor method.  The method returns a mock object of the appropriate
       mocked class.  The only caveat with this method is that in order for the attribute/values
       defaulting-ovveride stuff to work you have to use the defaultConstructor to set up your
       constructor.

           $mockClass->defaultConstructor('spider-man' => 'ben reilly');
           my $mockObject = $mockClass->create('batman' => 'bruce wayne', 'spider-man' => 'peter parker');

   getArgumentList
       I've found that I often want to know exactly how a method was called on a mock object,
       when I do I use getArgumentList.  This method takes three arguments, two are required and
       the third is often needed.  The first argument is the object Id for the object you want
       the tracking for, the second argument is the name of the method that you want the
       arguments from, and the third argument corresponds to the order of call for this method
       (not to be confused with the call order for all the methods).  The method returns an array
       which is a list of the arguments that were passed into the method.  In scalar context it
       returns a reference to an array.  The following example gets the arguments from the second
       time 'fooMethod' was called.

           my @arguments = $mockClass->getArgumentList("$mockObject", 'fooMethod', 1);

       If the third argument is not supplied, it returns an array of all of the argument lists.

   getNextObjectId
       Sometimes your mock objects are destroyed before you can get their object id.  Well in
       those cases you can get the cached object Id from the Test::MockClass object.  This method
       requires no arguments and returns object Ids suitable for use in any of the other
       Test::MockClass methods.  The method begins with the object id for the first object
       created, and returns subsequent ones until it runs out, in which case it returns undef,
       and then starts over.

           my $firstObjectId = $mockClass->getNextObjectId();

   getAttributeAccess
       Sometimes you need to track how the object's attributes are accessed.  Maybe someone's
       breaking your encapsulation, shame on them, or maybe the access is okay.  For whatever
       reason if you want a list of accesses for an object's underlying data structure just use
       getAttributeAccess method.  This method takes a single required argument which is the
       object id of the object you want the tracking for.  It returns a multi dimensional array,
       the first dimension corresponds to the order of accesses.  The second dimension contains
       the actual tracking information.  The first position [0] in this array describes the type
       of access, either 'store' or 'fetch'.  The second position [1] in this array corresponds
       to the attribute that was accessed, the key of the hash, the index of the array, or
       nothing for a scalar.  The third position in this array is only used when the access was
       of type 'store', and it contains the new value.  In scalar context it returns an array
       ref.

           my @accesses = $mockClass->getAttributeAccess("$mockObject");
           print "breaky\n" if(grep {$_[0] eq 'store'} @accesses);

       A second argument can be supplied which corresponds to the order that the access took
       place.

   noTracking
       Maybe my mock objects are too slow for you, what with all the tracking of interactions and
       such.  Maybe all you need is a mock object and you don't care how it was interated with.
       Maybe you have to make millions of mock objects and you just don't have the memory to
       support tracking.  Well fret not my friend, for the noTracking method is here to help you.
       Just call this method (no arguments required) and all the tracking will be disabled for
       any subsequent mock objects created.  I personally like tracking, so I switch it on by
       default.

           $mockClass->noTracking(); # no more tracking of methodcalls, constructor-calls, attribute-accesses

   tracking
       So you want to track some calls but not others?  Fine, use the tracking method to turn
       tracking back on for any subsequently created mock objects.

           $mockClass->tracking(); # now tracking is back on.

   constructor
       You want to use defaultConstructor or create, but you don't want to use 'new' as the name
       of your constructor?  That's fine, just pass in the name of the constructor you want to
       use/create to the constructor method.  Ugh, that's kinda confusing, an example will be
       simpler.

           $mockClass->constructor('create'); # change from 'new'.
           $mockClass->defaultConstructor(); # installs 'create'.
           my $mockObject = MockClass->create(); # calls 'create' on mocked class.

   inheritFrom
       This method allows your mock class to inherit from other mock classes or real classes.
       Since it basically just uses perl's inheritence, it's pretty transparent.  And yes, it
       does support multiple inheritence, though you don't have to use it if you don't wanna.

TODO

       Figure out how to add simple export/import mechanisms for mocked classes.  Make
       Test::MockClass less hash-centric. Stop breaking Tie::Watch's encapsulation. Provide mock
       objects with an interface to their own tracking. Make tracking and noTracking more fine-
       grained. Maybe find a safe way to clean up namespaces after the maker object goes out of
       scope. Write tests for arrayref and scalarref based objects. Write tests for unusual
       objects (regular expression, typeglob, filehandle, etc.)

SEE ALSO

       Alternatives: Test::MockObject, Test::MockMethod
       Testing systems: Test::Simple, Test::More, Test::Builder, Test::Harness
       xUnit testing: Test::SimpleUnit, Test::Unit, Test::Class

AUTHOR

       Jeremiah Jordan <jjordan@perlreason.com>

       Inspired by Test::MockObject by chromatic, and by Test::Unit::Mockup (ruby) by Michael
       Granger.  Both of whom were probably inspired by other people (J-unit, Xunit types maybe?)
       which all goes back to that sUnit guy.  Thanks to Stevan Little for the constructive
       criticism.

       Copyright (c) 2002, 2003, 2004, 2005 perl Reason, LLC. All Rights Reserved.

       This module is free software. It may be used, redistributed and/or modified under the
       terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html) or
       under the GPL.