man Test::MockClass (3): 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.)

AUTHOR

Jeremiah Jordan <[email protected]>

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.

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.