===================================
 Mock - Mocking and Test Utilities
===================================
--------------------------------------
 A Mock Library for Use With unittest
--------------------------------------

:Author: `Michael Foord`_
:Version: Mock 0.3.1
:Date: 2007/12/03
:Homepage: `Mock Homepage`_
:License: `BSD License`_
:Support: fuzzyman@voidspace.org.uk

.. meta::
   :description: Mock - a Python mocking and testing library for use
                 with unittest.
   :keywords: python, test, testing, mock, mocks, mocking, utilities, unittest, patching

.. contents:: The Mock Manual
.. sectnum::

.. _Mock Homepage: http://www.voidspace.org.uk/python/mock.html
.. _BSD License: http://www.voidspace.org.uk/python/license.shtml


Introduction
============

There are already several Python mocking libraries available, so why another one?

Most mocking libraries follow the 'record -> replay' pattern of mocking. I prefer the 'action -> assertion' pattern, which is more readable and intuitive particularly when working with the Python `unittest module <http://docs.python.org/lib/module-unittest.html>`_. For a discussion of the merits of the two approaches, see `Mocking, Patching, Stubbing: all that Stuff <http://www.voidspace.org.uk/python/articles/mocking.shtml>`_.

``mock`` provides a core ``Mock`` class that is intended to reduce the need to create a host of trivial stubs throughout your test suite. After performing an action, you can make assertions about which methods / attributes were used and arguments they were called with. You can also specify return values and set needed attributes in the normal way.

This approach is inspired by the testing patterns used at `Resolver Systems <http://www.resolversystems.com>`_.

It also provides utility functions / objects to assist with testing, particularly monkey patching.


Downloading
===========

The current version is **0.3.1**, dated 3rd December 2007. Mock is still experimental. The API may change or it may never get used! If you find bugs or have suggestions for improvements / extensions then please email me.

* `mock.py (module only) <http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?section=python&file=mock.py>`_
* `mock-0.3.1.zip (module, tests and documentation) <http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?section=python&file=mock-0.3.1.zip>`_
* `mock.txt (documentation) <http://www.voidspace.org.uk/python/docs/mock.txt>`_
* `Google Code Home & Subversion Repository <http://code.google.com/p/mock/>`_

You can checkout the latest development version from the Google Code Subversion repository with the following command:

    ``svn checkout http://mock.googlecode.com/svn/trunk/ mock-read-only``


Getting Started
===============

``Mock`` objects can be used for:

* Patching methods
* Recording method calls on objects

.. raw:: html

    {+coloring}
    >>> from mock import Mock
    >>> 
    >>> real = ProductionClass()
    >>> real.method = Mock()
    >>> 
    >>> real.method(3, 4, 5, key='value')
    >>>
    >>> real.method.called
    True
    >>> real.method.call_args
    ((3, 4, 5), {'key': 'value'})
    >>>
    >>> mock = Mock()
    >>> mock.something()
    >>> mock.method_calls
    [('something', (), {})]
    >>>
    >>> mock = Mock(methods=['something'])
    >>> mock.something()
    >>> mock.something_else()
    Traceback (most recent call last):
       ...
    AttributeError: object has no attribute 'something_else'
    {-coloring}

There are various ways of configuring the mock, including setting return values on the mock and its methods.

It also provides a useful ``sentinel`` object for providing unique objects in your tests:

.. raw:: html

    {+coloring}
    >>> from mock import sentinel
    >>> real = ProductionClass()
    >>> real.method = Mock()
    >>> 
    >>> real.method.return_value = sentinel.ReturnValue
    >>> real.method()
    <SentinelObject "ReturnValue">
    {-coloring}

There is also a decorator for doing module and class level patching. As modules and classes are effectively globals any patching has to be undone (or it persists into other tests). These decorators make it easier to test with module and class level patching:

.. raw:: html

    {+coloring}
    from mock import patch, sentinel
    
    original = SomeClass.attribute
    @patch(SomeClass, 'attribute', sentinel.Attribute)
    def test():
        self.assertEquals(SomeClass.attribute, sentinel.Attribute, "class attribute not patched")
    test()
    
    self.assertEquals(SomeClass.attribute, original, "attribute not restored")
    
    
    @patch('Package.Module', 'attribute', sentinel.Attribute)
    def test():
        # do something
    test()
    {-coloring}


If you don't want to call the decorated test function yourself, you can add ``apply`` as a decorator on top:

.. raw:: html

    {+coloring}
    @apply
    @patch('Package.Module', 'attribute', sentinel.Attribute)
    def test():
        # do something
    {-coloring}


A nice pattern is to actually decorate test methods themselves:

.. raw:: html

    {+coloring}
    
    @patch('Package.Module', 'attribute', sentinel.Attribute)
    def testMethod(self):
        # do something
    {-coloring}
    

If you want to patch with a Mock, you can use ``patch`` with only two arguments. The mock will be created for you and passed into the test function / method:

.. raw:: html

    {+coloring}
    
    @patch('Package.Module', 'method')
    def testMethod(self, mockMethod):
        # do something
    {-coloring}


API Documentation
=================

Mock
----

Initialisation
~~~~~~~~~~~~~~

.. raw:: html

    {+coloring}
    class Mock(object):
        def __init__(self, methods=None, spec=None)
    {-coloring}

``Mock`` has two optional arguments:

* ``methods``: a list of strings. Attempting to access attributes or methods not in this list will raise an ``AttributeError``. If this argument is not passed in then all attribute access will return a new mock object.

* ``spec``: This takes an existing object as the specification for the mock object. All attributes on the object (whether a class or an instance) are allowed, but accessing any other attributes will raise an ``AttributeError``. Passing in an object as the spec argument is the equivalent of passing in a list of strings to ``method`` with all the attributes on the object.


Calling
~~~~~~~

.. raw:: html

    {+coloring}
    def __call__(self, *args, **keywargs):
    {-coloring}
    
Mock objects are callable. The call will return the value set as the `return_value`_ attribute.

Calls made to the object will be recorded in the attributes_.


reset
~~~~~

.. raw:: html

    {+coloring}
    def reset(self):
    {-coloring}

The reset method resets all the call attributes on a mock object.

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock('hello')
    >>> mock.called
    True
    >>> mock.reset()
    >>> mock.called
    False
    {-coloring}

This can be useful where you want to make a series of assertions that reuse the same object. Note that ``reset`` also clears the return value and any child attributes. Attributes you have set using normal assignment will be left in place.


Attributes
~~~~~~~~~~

called
######

A boolean representing whether or not the mock object has been called.

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock.called
    False
    >>> mock()
    >>> mock.called
    True
    {-coloring}
    

return_value
############

Set this to configure the value returned by calling the mock.

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock.return_value = 'fish'
    >>> mock()
    'fish'
    {-coloring}


call_args
#########

This is either ``None`` (if the mock hasn't been called), or the arguments that the mock was last called with. This will in the form of a tuple: the first member is any ordered arguments the mock was called with (or an empty tuple) and the second member is any keyword arguments (or an empty dictionary):

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> print mock.call_args
    None
    >>> mock()
    >>> mock.call_args
    ((), {})
    >>> 
    >>> mock(3, 4, 5, key='fish', next='w00t!')
    >>> mock.call_args
    ((3, 4, 5), {'key': 'fish', 'next': 'w00t!'})
    {-coloring}


call_args_list
##############

This is a list of all the calls made to the mock object in sequence. Before any calls have been made it is an empty list.

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock()
    >>> mock(3, 4, 5, key='fish', next='w00t!')
    >>> mock.call_args_list
    [((), {}), ((3, 4, 5), {'key': 'fish', 'next': 'w00t!'})]
    {-coloring}


method_calls
############

As well as tracking calls to themselves, mocks also track calls to methods and attributes, and *their* methods and attributes:

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock.method()
    >>> mock.property.method.attribute()
    >>> mock.method_calls
    [('method', (), {}), ('property.method.attribute', (), {})]
    {-coloring}


Sentinel
--------

The ``sentinel`` object provides a convenient way of providing unique objects for your tests. See `Sentinel Examples`_.

Attributes are created on demand when you access them by name. Accessing the same attribute will always return the same object. The objects returned have a sensible repr so that test failure messages are readable.


Patch Decorator
----------------

patch
~~~~~

.. raw:: html

    {+coloring}
    def patch(target, attribute, new=None):
    {-coloring}

``patch`` decorates a function. Inside the body of the function, the ``target`` has ``attribute`` patched with a ``new`` object. When the function exits the patch is undone (which of course is done in a try-finally).

If you want to perform multiple patches then you can simply stack up the decorators on a function if you particularly feel the need.

If ``target`` is string, then ``patch`` will use it as a module name. The module is imported and the specified attribute patched with the new object. When the function exits the patch is undone (which of course is done in a try-finally). The module name can be dotted, e.g. ``package.module``.

If ``new`` is omitted, then a new ``Mock`` instance is supplied for you.


Examples
========

For further examples, see the unit tests included in the full distribution.

Mock Examples
-------------

Mock Patching Methods
~~~~~~~~~~~~~~~~~~~~~

``Mock`` is callable. If it is called then it sets a ``called`` attribute to ``True``.

This example tests that calling ``method`` results in a call to ``something``:

.. raw:: html

    {+coloring}
    def test_method_calls_something(self):
        real = ProductionClass()
        real.something = Mock()
        
        real.method()
        
        self.assertTrue(real.something.called, "method didn't call something")
    {-coloring}
    
If you want to catch the arguments then there is other information exposed:

.. raw:: html

    {+coloring}
    def test_method_calls_something(self):
        real = ProductionClass()
        real.something = Mock()
        
        real.method()
        
        self.assertEquals(real.something.call_count, 1, "something called incorrect number of times")
        
        args = ()
        keywargs = {}
        self.assertEquals(real.something.call_args, (args, keywargs), "something called with incorrect arguments")
        self.assertEquals(real.something.call_args_list, [(args, keywargs)], 
                          "something called with incorrect arguments")
    {-coloring}

Checking ``call_args_list`` tests how many times the mock was called, and the arguments for each call, in a single assertion.


Mock for Method Calls on an Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. raw:: html

    {+coloring}
    def test_closer_closes_something(self):
        real = ProductionClass()
        mock = Mock()
        
        real.closer(mock)
        
        self.assertTrue(mock.close.called, "closer didn't close something")
    {-coloring}

We don't have to do any work to provide the 'close' method on our mock. Accessing close creates it. So, if 'close' hasn't already been called then accessing it in the test will create it - but ``called`` will be ``False``.

As ``close`` is a mock object is has all the attributes from the previous example.


Limiting Available Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~

The disadvantage of the approach above is that *all* method access creates a new mock. This means that you can't tell if any methods were called that shouldn't have been. There are two ways round this. The first is by restricting the methods available on your mock.

.. raw:: html

    {+coloring}
    def test_closer_closes_something(self):
        real = ProductionClass()
        methods = ['close']
        mock = Mock(methods) # methods=methods is equivalent
        
        real.closer(mock)
        
        self.assertTrue(mock.close.called, "closer didn't close something")
    {-coloring}

If ``closer`` calls any methods on ``mock`` *other* than close, then an ``AttributeError`` will be raised.


Tracking all Method Calls
~~~~~~~~~~~~~~~~~~~~~~~~~

An alternative way to verify that only the expected methods have been accessed is to use the ``method_calls`` attribute of the mock. This records all calls to child attributes of the mock - and also to their children.

This is useful if you have a mock where you expect an attribute method to be called. You could access the attribute directly, but ``method_calls`` provides a convenient way of looking at all method calls:

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock.method()
    >>> mock.Property.method(10, x=53)
    >>> mock.method_calls
    [('method', (), {}), ('Property.method', (10,), {'x': 53})]
    >>> 
    {-coloring}

If you make an assertion about ``method_calls`` and any unexpected methods have been called, then the assertion will fail.


Setting Return Values and Setting Attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Setting the return values on a mock object is trivially easy:

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock.return_value = 3
    >>> mock()
    3
    {-coloring}

Of course you can do the same for methods on the mock:

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock.method.return_value = 3
    >>> mock.method()
    3
    {-coloring}

If you need an attribute setting on your mock, just do it:

.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> mock.x = 3
    >>> mock.x
    3
    {-coloring}

Sometimes you want to mock up a more complex situation, like for example ``mock.connection.cursor().execute("SELECT 1")``:


.. raw:: html

    {+coloring}
    >>> mock = Mock()
    >>> cursor = Mock()
    >>> mock.connection.cursor.return_value = cursor
    >>>
    >>> mock.connection.cursor().execute("SELECT 1")
    >>> mock.method_calls
    [('connection.cursor', (), {})]
    >>> cursor.method_calls
    [('execute', ('SELECT 1',), {})]
    >>> 
    {-coloring}


Creating a Mock from an Existing Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One problem with over use of mocking is that it couples your tests to the implementation of your mocks rather than your real code. Suppose you have a class that implements ``some_method``. In a test for another class, you provide a mock of this object that *also* provides ``some_method``. If later you refactor the first class, so that it no longer has ``some_method`` - then your tests will continue to pass even though your code is now broken!

``Mock`` allows you to provide an object as a specification for the mock, using the ``spec`` keyword argument. Accessing methods / attributes on the mock that don't exist on your specification object will immediately raise an attribute error. If you change the implementation of your specification, then tests that use that class will start failing immediately without you having to instantiate the class in those tests.



.. raw:: html

    {+coloring}
    >>> mock = Mock(spec=SomeClass)
    >>>
    >>> mock.old_method()
    Traceback (most recent call last):
       ...
    AttributeError: object has no attribute 'old_method'
    {-coloring}


Sentinel Examples
-----------------

Sometimes when testing you need to test that a specific object is passed as an argument to another method, or returned. It can be common to create named sentinel objects to test this. ``sentinel`` provides a convenient way of creating and testing the identity of objects like this.

In this example we monkey patch ``method`` to return ``sentinel.ReturnValue``. We want to test that this is the value returned when we call ``something``.


.. raw:: html

    {+coloring}
    from mock import Mock, sentinel
    
    real = ProductionClass()
    
    real.method = Mock()
    real.method.return_value = sentinel.ReturnValue
    
    returned = real.something()
    self.assertEquals(returned, sentinel.ReturnValue, "something returned the wrong value")
    {-coloring}



Patch Decorator Examples
------------------------

A common need in tests is to patch a class attribute or a module attribute, for example patching a builtin or patching a class in a module to test that it is instantiated. Modules and classes are effectively global, so patching on them has to be undone after the test or the patch will persist into other tests and cause hard to diagnose problems.

The patch_ provides a convenient way of doing this. 

.. raw:: html

    {+coloring}
    mock = Mock()
    @patch(SomeClass, 'class_method', mock) 
    def test():
        SomeClass.class_method()
    test()
    
    self.assertTrue(mock.called, "class_method not called")
    {-coloring}

The decorator is applied to a function (called ``test`` above). The patching only applies inside the body of the function. You have to call the function explicitly, this can be useful as the test function can take arguments and be used to implement several tests, it can also return values.

They can be stacked to perform multiple simultaneous patches:

.. raw:: html

    {+coloring}
    mock1 = Mock()
    mock2 = Mock()
    
    @patch(SomeClass, 'class_method', mock1) 
    @patch(SomeClass, 'static_method', mock2) 
    def test():
        SomeClass.class_method()
        SomeClass.static_method()
    test()
    
    self.assertTrue(mock1.called, "class_method not called")
    self.assertTrue(mock2.called, "static_method not called")
    {-coloring}

If you are patching a module (including ``__builtin__``) then supply a module name instead of an object to patch:

.. raw:: html

    {+coloring}
    mock = Mock()
    mock.return_value = sentinel.Handle
    
    @patch('__builtin__', 'open', mock) 
    def test():
        return open('filename', 'r')
    
    handle = test()
    
    self.assertEquals(mock.call_args, (('filename', 'r'), {}), "open not called correctly")
    self.assertEquals(handle, sentinel.Handle, "incorrect file handle returned")
    {-coloring}
    
The module name can be 'dotted', in the form ``package.module`` if needed.


If you don't want to call the decorated test function yourself, you can add ``apply`` as a decorator on top:

.. raw:: html

    {+coloring}
    @apply
    @patch('Package.Module', 'attribute', sentinel.Attribute)
    def test():
        # do something
    {-coloring}


A nice pattern is to actually decorate test methods themselves:

.. raw:: html

    {+coloring}
    
    @patch(SomeClass, 'attribute', sentinel.Attribute)
    def testMethod(self):
        self.assertEquals(SomeClass.attribute, sentinel.Attribute, "SomeClass not patched")
    {-coloring}
    
    
If you omit the third argument to ``patch`` then the attribute will be patched with a mock for you. The mock will be passed in as extra argument(s) to the function / method under test:

.. raw:: html

    {+coloring}
    
    @patch(SomeClass, 'staticmethod')
    def testMethod(self, mockMethod):
        SomeClass.staticmethod()
        self.assertEquals(mockMethod.called, "SomeClass not patched with a mock")
    {-coloring}


You can stack up multiple patch decorators using this pattern:

.. raw:: html

    {+coloring}
    
    @patch('Module', 'ClassName1')
    @patch('Module', 'ClassName2')
    def testMethod(self, mockClass1, mockClass2):
        ClassName1()
        ClassName2()
        self.assertEquals(mockClass1.called, "ClassName1 not patched")
        self.assertEquals(mockClass2.called, "ClassName2 not patched")
    {-coloring}




Limitations
===========

There are various disadvantages and things that Mock doesn't (yet) do. 

* It doesn't wrap objects. If you need to pass calls through to the real object *and* record them then you can't yet do that.
* You can specify return values, but they are fixed values. You may want to provide a factory function to provide a sequence of return values for example.
* ``Mock`` has several attributes. This makes it unsuitable for mocking objects that use these attribute names. A way round this would be to provide ``start`` and ``stop`` (or similar) methods that *hide* these attributes when needed. 



CHANGELOG
=========


2007/12/03  Version 0.3.1
-------------------------

``patch`` maintains the name of decorated functions for compatibility with nose test autodiscovery.

Tests decorated with ``path`` that use the two argument form (implicit mock creation) will receive the mock(s) passed in as extra arguments.

Thanks to Kevin Dangoor for these changes.


2007/11/30  Version 0.3.0
-------------------------

Removed ``patch_module``. ``patch`` can now take a string as the first argument for patching modules.

The third argument to ``patch`` is optional - a mock will be created by default if it is not passed in.



2007/11/21  Version 0.2.1
-------------------------

Bug fix, allows reuse of functions decorated with ``patch`` and ``patch_module``.


2007/11/20  Version 0.2.0
-------------------------


Added ``spec`` keyword argument for creating ``Mock`` objects from a specification object.

Added ``patch`` and ``patch_module`` monkey patching decorators.

Added ``sentinel`` for convenient access to unique objects.

Distribution includes unit tests.


2007/11/19  Version 0.1.0
-------------------------

Initial release.




.. _Michael Foord: http://www.voidspace.org.uk/python/weblog/index.shtml