#
# (c) Dave Kirby 2001 - 2005
# mock@thedeveloperscoach.com
#
# Original call interceptor and call assertion code by Phil Dawes (pdawes@users.sourceforge.net)
# Call interceptor code enhanced by Bruce Cropley (cropleyb@yahoo.com.au)
#
# This Python module and associated files are released under the FreeBSD
# license. Essentially, you can do what you like with it except pretend you wrote
# it yourself.
#
#
# Copyright (c) 2005, Dave Kirby
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
#
# * Neither the name of this library nor the names of its
# contributors may be used to endorse or promote products derived from
# this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# mock@thedeveloperscoach.com
"""
Mock object library for Python. Mock objects can be used when unit testing
to remove a dependency on another production class. They are typically used
when the dependency would either pull in lots of other classes, or
significantly slow down the execution of the test.
They are also used to create exceptional conditions that cannot otherwise
be easily triggered in the class under test.
"""
__version__ = "0.1.0"
# Added in Python 2.1
import inspect
import re
class MockInterfaceError(Exception):
pass
class Mock:
"""
The Mock class emulates any other class for testing purposes.
All method calls are stored for later examination.
"""
def __init__(self, returnValues=None, realClass=None):
"""
The Mock class constructor takes a dictionary of method names and
the values they return. Methods that are not in the returnValues
dictionary will return None.
You may also supply a class whose interface is being mocked.
All calls will be checked to see if they appear in the original
interface. Any calls to methods not appearing in the real class
will raise a MockInterfaceError. Any calls that would fail due to
non-matching parameter lists will also raise a MockInterfaceError.
Both of these help to prevent the Mock class getting out of sync
with the class it is Mocking.
"""
self.mockCalledMethods = {}
self.mockAllCalledMethods = []
self.mockReturnValues = returnValues or {}
self.mockExpectations = {}
self.realClassMethods = None
if realClass:
self.realClassMethods = dict(inspect.getmembers(realClass, inspect.isroutine))
for retMethod in self.mockReturnValues.keys():
if not self.realClassMethods.has_key(retMethod):
raise MockInterfaceError("Return value supplied for method '%s' that was not in the original class" % retMethod)
self._setupSubclassMethodInterceptors()
def _setupSubclassMethodInterceptors(self):
methods = inspect.getmembers(self.__class__,inspect.isroutine)
baseMethods = dict(inspect.getmembers(Mock, inspect.ismethod))
for m in methods:
name = m[0]
# Don't record calls to methods of Mock base class.
if not name in baseMethods:
self.__dict__[name] = MockCallable(name, self, handcrafted=True)
def __getattr__(self, name):
return MockCallable(name, self)
def mockAddReturnValues(self, **methodReturnValues ):
self.mockReturnValues.update(methodReturnValues)
def mockSetExpectation(self, name, testFn, after=0, until=0):
self.mockExpectations.setdefault(name, []).append((testFn,after,until))
def _checkInterfaceCall(self, name, callParams, callKwParams):
"""
Check that a call to a method of the given name to the original
class with the given parameters would not fail. If it would fail,
raise a MockInterfaceError.
Based on the Python 2.3.3 Reference Manual section 5.3.4: Calls.
"""
if self.realClassMethods == None:
return
if not self.realClassMethods.has_key(name):
raise MockInterfaceError("Calling mock method '%s' that was not found in the original class" % name)
func = self.realClassMethods[name]
try:
args, varargs, varkw, defaults = inspect.getargspec(func)
except TypeError:
# func is not a Python function. It is probably a builtin,
# such as __repr__ or __coerce__. TODO: Checking?
# For now assume params are OK.
return
# callParams doesn't include self; args does include self.
numPosCallParams = 1 + len(callParams)
if numPosCallParams > len(args) and not varargs:
raise MockInterfaceError("Original %s() takes at most %s arguments (%s given)" %
(name, len(args), numPosCallParams))
# Get the number of positional arguments that appear in the call,
# also check for duplicate parameters and unknown parameters
numPosSeen = _getNumPosSeenAndCheck(numPosCallParams, callKwParams, args, varkw)
lenArgsNoDefaults = len(args) - len(defaults or [])
if numPosSeen < lenArgsNoDefaults:
raise MockInterfaceError("Original %s() takes at least %s arguments (%s given)" % (name, lenArgsNoDefaults, numPosSeen))
def mockGetAllCalls(self):
"""
Return a list of MockCall objects,
representing all the methods in the order they were called.
"""
return self.mockAllCalledMethods
getAllCalls = mockGetAllCalls # deprecated - kept for backward compatibility
def mockGetNamedCalls(self, methodName):
"""
Return a list of MockCall objects,
representing all the calls to the named method in the order they were called.
"""
return self.mockCalledMethods.get(methodName, [])
getNamedCalls = mockGetNamedCalls # deprecated - kept for backward compatibility
def mockCheckCall(self, index, name, *args, **kwargs):
'''test that the index-th call had the specified name and parameters'''
call = self.mockAllCalledMethods[index]
assert name == call.getName(), "%r != %r" % (name, call.getName())
call.checkArgs(*args, **kwargs)
def _getNumPosSeenAndCheck(numPosCallParams, callKwParams, args, varkw):
"""
Positional arguments can appear as call parameters either named as
a named (keyword) parameter, or just as a value to be matched by
position. Count the positional arguments that are given by either
keyword or position, and check for duplicate specifications.
Also check for arguments specified by keyword that do not appear
in the method's parameter list.
"""
posSeen = {}
for arg in args[:numPosCallParams]:
posSeen[arg] = True
for kwp in callKwParams:
if posSeen.has_key(kwp):
raise MockInterfaceError("%s appears as both a positional and named parameter." % kwp)
if kwp in args:
posSeen[kwp] = True
elif not varkw:
raise MockInterfaceError("Original method does not have a parameter '%s'" % kwp)
return len(posSeen)
class MockCall:
"""
MockCall records the name and parameters of a call to an instance
of a Mock class. Instances of MockCall are created by the Mock class,
but can be inspected later as part of the test.
"""
def __init__(self, name, params, kwparams ):
self.name = name
self.params = params
self.kwparams = kwparams
def checkArgs(self, *args, **kwargs):
assert args == self.params, "%r != %r" % (args, self.params)
assert kwargs == self.kwparams, "%r != %r" % (kwargs, self.kwparams)
def getParam( self, n ):
if isinstance(n, int):
return self.params[n]
elif isinstance(n, str):
return self.kwparams[n]
else:
raise IndexError, 'illegal index type for getParam'
def getNumParams(self):
return len(self.params)
def getNumKwParams(self):
return len(self.kwparams)
def getName(self):
return self.name
#pretty-print the method call
def __str__(self):
s = self.name + "("
sep = ''
for p in self.params:
s = s + sep + repr(p)
sep = ', '
items = self.kwparams.items()
items.sort()
for k,v in items:
s = s + sep + k + '=' + repr(v)
sep = ', '
s = s + ')'
return s
def __repr__(self):
return self.__str__()
class MockCallable:
"""
Intercepts the call and records it, then delegates to either the mock's
dictionary of mock return values that was passed in to the constructor,
or a handcrafted method of a Mock subclass.
"""
def __init__(self, name, mock, handcrafted=False):
self.name = name
self.mock = mock
self.handcrafted = handcrafted
def __call__(self, *params, **kwparams):
self.mock._checkInterfaceCall(self.name, params, kwparams)
thisCall = self.recordCall(params,kwparams)
self.checkExpectations(thisCall, params, kwparams)
return self.makeCall(params, kwparams)
def recordCall(self, params, kwparams):
"""
Record the MockCall in an ordered list of all calls, and an ordered
list of calls for that method name.
"""
thisCall = MockCall(self.name, params, kwparams)
calls = self.mock.mockCalledMethods.setdefault(self.name, [])
calls.append(thisCall)
self.mock.mockAllCalledMethods.append(thisCall)
return thisCall
def makeCall(self, params, kwparams):
if self.handcrafted:
allPosParams = (self.mock,) + params
func = _findFunc(self.mock.__class__, self.name)
if not func:
raise NotImplementedError
return func(*allPosParams, **kwparams)
else:
returnVal = self.mock.mockReturnValues.get(self.name)
if isinstance(returnVal, ReturnValuesBase):
returnVal = returnVal.next()
return returnVal
def checkExpectations(self, thisCall, params, kwparams):
if self.name in self.mock.mockExpectations:
callsMade = len(self.mock.mockCalledMethods[self.name])
for (expectation, after, until) in self.mock.mockExpectations[self.name]:
if callsMade > after and (until==0 or callsMade < until):
assert expectation(self.mock, thisCall, len(self.mock.mockAllCalledMethods)-1), 'Expectation failed: '+str(thisCall)
def _findFunc(cl, name):
""" Depth first search for a method with a given name. """
if cl.__dict__.has_key(name):
return cl.__dict__[name]
for base in cl.__bases__:
func = _findFunc(base, name)
if func:
return func
return None
class ReturnValuesBase:
def next(self):
try:
return self.iter.next()
except StopIteration:
raise AssertionError("No more return values")
def __iter__(self):
return self
class ReturnValues(ReturnValuesBase):
def __init__(self, *values):
self.iter = iter(values)
class ReturnIterator(ReturnValuesBase):
def __init__(self, iterator):
self.iter = iter(iterator)
def expectParams(*params, **keywords):
'''check that the callObj is called with specified params and keywords
'''
def fn(mockObj, callObj, idx):
return callObj.params == params and callObj.kwparams == keywords
return fn
def expectAfter(*methods):
'''check that the function is only called after all the functions in 'methods'
'''
def fn(mockObj, callObj, idx):
calledMethods = [method.getName() for method in mockObj.mockGetAllCalls()]
#skip last entry, since that is the current call
calledMethods = calledMethods[:-1]
for method in methods:
if method not in calledMethods:
return False
return True
return fn
def expectException(exception, *args, **kwargs):
''' raise an exception when the method is called
'''
def fn(mockObj, callObj, idx):
raise exception(*args, **kwargs)
return fn
def expectParam(paramIdx, cond):
'''check that the callObj is called with parameter specified by paramIdx (a position index or keyword)
fulfills the condition specified by cond.
cond is a function that takes a single argument, the value to test.
'''
def fn(mockObj, callObj, idx):
param = callObj.getParam(paramIdx)
return cond(param)
return fn
def EQ(value):
def testFn(param):
return param == value
return testFn
def NE(value):
def testFn(param):
return param != value
return testFn
def GT(value):
def testFn(param):
return param > value
return testFn
def LT(value):
def testFn(param):
return param < value
return testFn
def GE(value):
def testFn(param):
return param >= value
return testFn
def LE(value):
def testFn(param):
return param <= value
return testFn
def AND(*condlist):
def testFn(param):
for cond in condlist:
if not cond(param):
return False
return True
return testFn
def OR(*condlist):
def testFn(param):
for cond in condlist:
if cond(param):
return True
return False
return testFn
def NOT(cond):
def testFn(param):
return not cond(param)
return testFn
def MATCHES(regex, *args, **kwargs):
compiled_regex = re.compile(regex, *args, **kwargs)
def testFn(param):
return compiled_regex.match(param) != None
return testFn
def SEQ(*sequence):
iterator = iter(sequence)
def testFn(param):
try:
cond = iterator.next()
except StopIteration:
raise AssertionError('SEQ exhausted')
return cond(param)
return testFn
def IS(instance):
def testFn(param):
return param is instance
return testFn
def ISINSTANCE(class_):
def testFn(param):
return isinstance(param, class_)
return testFn
def ISSUBCLASS(class_):
def testFn(param):
return issubclass(param, class_)
return testFn
def CONTAINS(val):
def testFn(param):
return val in param
return testFn
def IN(container):
def testFn(param):
return param in container
return testFn
def HASATTR(attr):
def testFn(param):
return hasattr(param, attr)
return testFn
def HASMETHOD(method):
def testFn(param):
return hasattr(param, method) and callable(getattr(param, method))
return testFn
CALLABLE = callable
|