Mock v0.7.2 documentation

This Page

Patch Decorators

The patch decorators are used for patching objects only within the scope of the function they decorate. They automatically handle the unpatching for you, even if exceptions are raised. All of these functions can also be used in with statements or as class decorators.



patch is straightforward to use. The key is to do the patching in the right namespace. See the section where to patch.

patch(target, new=<SentinelObject "DEFAULT">, spec=None, create=False, mocksignature=False, spec_set=None)

patch acts as a function decorator, class decorator or a context manager. Inside the body of the function or with statement, the target (specified in the form ‘PackageName.ModuleName.ClassName’) is patched with a new object. When the function/with statement exits the patch is undone.

The target is imported and the specified attribute patched with the new object, so it must be importable from the environment you are calling the decorator from.

If new is omitted, then a new Mock is created and passed in as an extra argument to the decorated function.

The spec and spec_set keyword arguments are passed to the Mock if patch is creating one for you.

In addition you can pass spec=True or spec_set=True, which causes patch to pass in the object being mocked as the spec/spec_set object.

If mocksignature is True then the patch will be done with a function created by mocking the one being replaced. If the object being replaced is a class then the signature of __init__ will be copied. If the object being replaced is a callable object then the signature of __call__ will be copied.

By default patch will fail to replace attributes that don’t exist. If you pass in ‘create=True’ and the attribute doesn’t exist, patch will create the attribute for you when the patched function is called, and delete it again afterwards. This is useful for writing tests against attributes that your production code creates at runtime. It is off by by default because it can be dangerous. With it switched on you can write passing tests against APIs that don’t actually exist!

Patch can be used as a TestCase class decorator. It works by decorating each test method in the class. This reduces the boilerplate code when your test methods share a common patchings set.

Patch can be used with the with statement, if this is available in your version of Python. Here the patching applies to the indented block after the with statement. If you use “as” then the patched object will be bound to the name after the “as”; very useful if patch is creating a mock object for you.

patch.dict(...) and patch.object(...) are available for alternate use-cases.


Patching a class replaces the class with a Mock instance. If the class is instantiated in the code under test then it will be the return_value of the mock that will be used.

If the class is instantiated multiple times you could use Mock.side_effect to return a new mock each time. Alternatively you can set the return_value to be anything you want.

To configure return values on methods of instances on the patched class you must do this on the return_value. For example:

>>> @patch('package.module.Class')
... def test(MockClass):
...     instance = MockClass.return_value
...     instance.method.return_value = 'foo'
...     from package.module import Class
...     assert Class() is instance
...     assert Class().method() == 'foo'
>>> test()


patch.object(target, attribute, new=DEFAULT, spec=None, create=False, mocksignature=False, spec_set=None)

patch the named member (attribute) on an object (target) with a mock object.

Arguments new, spec, create, mocksignature and spec_set have the same meaning as for patch.

You can either call patch.object with three arguments or two arguments. The three argument form takes the object to be patched, the attribute name and the object to replace the attribute with.

When calling with the two argument form you omit the replacement object, and a mock is created for you and passed in as an extra argument to the decorated function:

>>> @patch.object(SomeClass, 'class_method')
... def test(mock_method):
...     SomeClass.class_method(3)
...     mock_method.assert_called_with(3)
>>> test()

spec and create have the same meaning as for the patch decorator.

patch.object is also a context manager and can be used with with statements in the same way as patch. It can also be used as a class decorator with same semantics as patch.


Deprecated since version 0.7: This is the same as patch.object. Use the renamed version.


patch.dict(in_dict, values=(), clear=False)

Patch a dictionary and restore the dictionary to its original state after the test.

in_dict can be a dictionary or a mapping like container. If it is a mapping then it must at least support getting, setting and deleting items plus iterating over keys.

in_dict can also be a string specifying the name of the dictionary, which will then be fetched by importing it.

values can be a dictionary of values to set in the dictionary. values can also be an iterable of (key, value) pairs.

If clear is True then the dictionary will be cleared before the new values are set.

Like patch() and patch.object() patch.dict can be used as a decorator or a context manager. It can be used to add members to a dictionary, or simply let a test change a dictionary, and ensure the dictionary is restored when the test ends.

>>> from mock import patch
>>> foo = {}
>>> with patch.dict(foo, {'newkey': 'newvalue'}):
...     assert foo == {'newkey': 'newvalue'}
>>> assert foo == {}

>>> import os
>>> with patch.dict('os.environ', {'newkey': 'newvalue'}):
...     print os.environ['newkey']
>>> assert 'newkey' not in os.environ

patch methods: start and stop

All three patchers have start and stop methods. These make it simpler to do patching in setUp methods or where you want to do multiple patches without nesting decorators or with statements.

To use them call patch, patch.object or patch.dict as normal and keep a reference to the returned patcher object. You can then call start to put the patch in place and stop to undo it.

If you are using patch to create a mock for you then it will be returned by the call to patcher.start.

>>> patcher = patch('package.module.ClassName')
>>> from package import module
>>> original = module.ClassName
>>> new_mock = patcher.start()
>>> assert module.ClassName is not original
>>> assert module.ClassName is new_mock
>>> patcher.stop()
>>> assert module.ClassName is original
>>> assert module.ClassName is not new_mock

A typical use case for this might be for doing multiple patches in the setUp method of a TestCase:

>>> class MyTest(TestCase):
...     def setUp(self):
...         self.patcher1 = patch('package.module.Class1')
...         self.patcher2 = patch('package.module.Class2')
...         self.MockClass1 = self.patcher1.start()
...         self.MockClass2 = self.patcher2.start()
...     def tearDown(self):
...         self.patcher1.stop()
...         self.patcher2.stop()
...     def test_something(self):
...         assert package.module.Class1 is self.MockClass1
...         assert package.module.Class2 is self.MockClass2
>>> MyTest('test_something').run()


If you use this technique you must ensure that the patching is “undone” by calling stop. This can be fiddlier than you might think, because if an exception is raised in the setUp then tearDown is not called. unittest2 cleanup functions make this easier.

>>> class MyTest(TestCase):
...     def setUp(self):
...         patcher = patch('package.module.Class')
...         self.MockClass = patcher.start()
...         self.addCleanup(patcher.stop)
...     def test_something(self):
...         assert package.module.Class is self.MockClass
>>> MyTest('test_something').run()

As an added bonus you no longer need to keep a reference to the patcher object.

In fact start and stop are just aliases for the context manager __enter__ and __exit__ methods.

Nesting Patch Decorators

If you want to perform multiple patches then you can simply stack up the decorators.

You can stack up multiple patch decorators using this pattern:

>>> @patch.object(SomeClass, 'class_method')
... @patch.object(SomeClass, 'static_method')
... def test(mock1, mock2):
...     assert SomeClass.static_method is mock1
...     assert SomeClass.class_method is mock2
...     SomeClass.static_method('foo')
...     SomeClass.class_method('bar')
...     return mock1, mock2
>>> mock1, mock2 = test()
>>> mock1.assert_called_once_with('foo')
>>> mock2.assert_called_once_with('bar')

Note that the decorators are applied from the bottom upwards. This is the standard way that Python applies decorators. The order of the created mocks passed into your test function matches this order.

Like all context-managers patches can be nested using contextlib’s nested function; every patching will appear in the tuple after “as”:

>>> from contextlib import nested
>>> with nested(
...         patch('package.module.ClassName1'),
...         patch('package.module.ClassName2')
...     ) as (MockClass1, MockClass2):
...     assert package.module.ClassName1 is MockClass1
...     assert package.module.ClassName2 is MockClass2

Where to patch

patch works by (temporarily) changing the object that a name points to with another one. There can be many names pointing to any individual object, so for patching to work you must ensure that you patch the name used by the system under test.

The basic principle is that you patch where an object is used, which is not necessarily the same place as where it is defined. A couple of examples will help to clarify this.

Imagine we have a project that we want to test with the following structure:
    -> Defines SomeClass
    -> from a import SomeClass
    -> some_function instantiates SomeClass

Now we want to test some_function but we want to mock out SomeClass using patch. The problem is that when we import module b, which we will have to do then it imports SomeClass from module a. If we use patch to mock out a.SomeClass then it will have no effect on our test; module b already has a reference to the real SomeClass and it looks like our patching had no effect.

The key is to patch out SomeClass where it is used (or where it is looked up ). In this case some_function will actually look up SomeClass in module b, where we have imported it. The patching should look like:


However, consider the alternative scenario where instead of from a import SomeClass module b does import a and some_function uses a.SomeClass. Both of these import forms are common. In this case the class we want to patch is being looked up on the a module and so we have to patch a.SomeClass instead:


Patching Descriptors and Proxy Objects

Since version 0.6.0 both patch and patch.object have been able to correctly patch and restore descriptors: class methods, static methods and properties. You should patch these on the class rather than an instance.

Since version 0.7.0 patch and patch.object work correctly with some objects that proxy attribute access, like the django setttings object.


In django import settings and from django.conf import settings return different objects. If you are using libraries / apps that do both you may have to patch both. Grrr...