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.
+Note
+patch is straightforward to use. The key is to do the patching in the +right namespace. See the section where to patch.
+patch acts as a function decorator, class decorator or a context +manager. Inside the body of the function or with statement, the target +is patched with a new object. When the function/with statement exits +the patch is undone.
+If new is omitted, then the target is replaced with a +MagicMock. If patch is used as a decorator and new is +omitted, the created mock is passed in as an extra argument to the +decorated function. If patch is used as a context manager the created +mock is returned by the context manager.
+target should be a string in the form ‘package.module.ClassName’. The +target is imported and the specified object replaced with the new +object, so the target must be importable from the environment you are +calling patch from. The target is imported when the decorated function +is executed, not at decoration time.
+The spec and spec_set keyword arguments are passed to the MagicMock +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.
+new_callable allows you to specify a different class, or callable object, +that will be called to create the new object. By default MagicMock is +used.
+A more powerful form of spec is autospec. If you set autospec=True +then the mock with be created with a spec from the object being replaced. +All attributes of the mock will also have the spec of the corresponding +attribute of the object being replaced. Methods and functions being mocked +will have their arguments checked and will raise a TypeError if they are +called with the wrong signature. For mocks +replacing a class, their return value (the ‘instance’) will have the same +spec as the class. See the create_autospec() function and +Autospeccing.
+Instead of autospec=True you can pass autospec=some_object to use an +arbitrary object as the spec instead of the one being replaced.
+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 finds +tests by looking for method names that start with patch.TEST_PREFIX. +By default this is test, which matches the way unittest finds tests. +You can specify an alternative prefix by setting patch.TEST_PREFIX.
+Patch can be used as a context manager, with the with statement. 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 takes arbitrary keyword arguments. These will be passed to +the Mock (or new_callable) on construction.
+patch.dict(...), patch.multiple(...) and patch.object(...) are +available for alternate use-cases.
+patch as function decorator, creating the mock for you and passing it into +the decorated function:
+>>> @patch('__main__.SomeClass')
+... def function(normal_argument, mock_class):
+... print mock_class is SomeClass
+...
+>>> function(None)
+True
+Patching a class replaces the class with a MagicMock 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 +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:
+>>> class Class(object):
+... def method(self):
+... pass
+...
+>>> with patch('__main__.Class') as MockClass:
+... instance = MockClass.return_value
+... instance.method.return_value = 'foo'
+... assert Class() is instance
+... assert Class().method() == 'foo'
+...
+If you use spec or spec_set and patch is replacing a class, then the +return value of the created mock will have the same spec.
+>>> Original = Class
+>>> patcher = patch('__main__.Class', spec=True)
+>>> MockClass = patcher.start()
+>>> instance = MockClass()
+>>> assert isinstance(instance, Original)
+>>> patcher.stop()
+The new_callable argument is useful where you want to use an alternative +class to the default MagicMock for the created mock. For example, if +you wanted a NonCallableMock to be used:
+>>> thing = object()
+>>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing:
+... assert thing is mock_thing
+... thing()
+...
+Traceback (most recent call last):
+ ...
+TypeError: 'NonCallableMock' object is not callable
+Another use case might be to replace an object with a StringIO instance:
+>>> from StringIO import StringIO
+>>> def foo():
+... print 'Something'
+...
+>>> @patch('sys.stdout', new_callable=StringIO)
+... def test(mock_stdout):
+... foo()
+... assert mock_stdout.getvalue() == 'Something\n'
+...
+>>> test()
+When patch is creating a mock for you, it is common that the first thing +you need to do is to configure the mock. Some of that configuration can be done +in the call to patch. Any arbitrary keywords you pass into the call will be +used to set attributes on the created mock:
+>>> patcher = patch('__main__.thing', first='one', second='two')
+>>> mock_thing = patcher.start()
+>>> mock_thing.first
+'one'
+>>> mock_thing.second
+'two'
+As well as attributes on the created mock attributes, like the +return_value and side_effect, of child mocks can +also be configured. These aren’t syntactically valid to pass in directly as +keyword arguments, but a dictionary with these as keys can still be expanded +into a patch call using **:
+>>> config = {'method.return_value': 3, 'other.side_effect': KeyError}
+>>> patcher = patch('__main__.thing', **config)
+>>> mock_thing = patcher.start()
+>>> mock_thing.method()
+3
+>>> mock_thing.other()
+Traceback (most recent call last):
+ ...
+KeyError
+patch the named member (attribute) on an object (target) with a mock +object.
+patch.object can be used as a decorator, class decorator or a context +manager. Arguments new, spec, create, spec_set, autospec and +new_callable have the same meaning as for patch. Like patch, +patch.object takes arbitrary keyword arguments for configuring the mock +object it creates.
+When used as a class decorator patch.object honours patch.TEST_PREFIX +for choosing which methods to wrap.
+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, create and the other arguments to patch.object have the same +meaning as they do for patch.
+Patch a dictionary, or dictionary like object, 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.
+patch.dict can also be called with arbitrary keyword arguments to set +values in the dictionary.
+patch.dict can be used as a context manager, decorator or class +decorator. When used as a class decorator patch.dict honours +patch.TEST_PREFIX for choosing which methods to wrap.
+patch.dict 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']
+...
+newvalue
+>>> assert 'newkey' not in os.environ
+Keywords can be used in the patch.dict call to set values in the dictionary:
+>>> mymodule = MagicMock()
+>>> mymodule.function.return_value = 'fish'
+>>> with patch.dict('sys.modules', mymodule=mymodule):
+... import mymodule
+... mymodule.function('some', 'args')
+...
+'fish'
+patch.dict can be used with dictionary like objects that aren’t actually +dictionaries. At the very minimum they must support item getting, setting, +deleting and either iteration or membership test. This corresponds to the +magic methods __getitem__, __setitem__, __delitem__ and either +__iter__ or __contains__.
+>>> class Container(object):
+... def __init__(self):
+... self.values = {}
+... def __getitem__(self, name):
+... return self.values[name]
+... def __setitem__(self, name, value):
+... self.values[name] = value
+... def __delitem__(self, name):
+... del self.values[name]
+... def __iter__(self):
+... return iter(self.values)
+...
+>>> thing = Container()
+>>> thing['one'] = 1
+>>> with patch.dict(thing, one=2, two=3):
+... assert thing['one'] == 2
+... assert thing['two'] == 3
+...
+>>> assert thing['one'] == 1
+>>> assert list(thing) == ['one']
+Perform multiple patches in a single call. It takes the object to be +patched (either as an object or a string to fetch the object by importing) +and keyword arguments for the patches:
+with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
+ ...
+Use DEFAULT as the value if you want patch.multiple to create +mocks for you. In this case the created mocks are passed into a decorated +function by keyword, and a dictionary is returned when patch.multiple is +used as a context manager.
+patch.multiple can be used as a decorator, class decorator or a context +manager. The arguments spec, spec_set, create, autospec and +new_callable have the same meaning as for patch. These arguments will +be applied to all patches done by patch.multiple.
+When used as a class decorator patch.multiple honours patch.TEST_PREFIX +for choosing which methods to wrap.
+If you want patch.multiple to create mocks for you, then you can use +DEFAULT as the value. If you use patch.multiple as a decorator +then the created mocks are passed into the decorated function by keyword.
+>>> thing = object()
+>>> other = object()
+
+>>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
+... def test_function(thing, other):
+... assert isinstance(thing, MagicMock)
+... assert isinstance(other, MagicMock)
+...
+>>> test_function()
+patch.multiple can be nested with other patch decorators, but put arguments +passed by keyword after any of the standard arguments created by patch:
+>>> @patch('sys.exit')
+... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
+... def test_function(mock_exit, other, thing):
+... assert 'other' in repr(other)
+... assert 'thing' in repr(thing)
+... assert 'exit' in repr(mock_exit)
+...
+>>> test_function()
+If patch.multiple is used as a context manager, the value returned by the +context manger is a dictionary where created mocks are keyed by name:
+>>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values:
+... assert 'other' in repr(values['other'])
+... assert 'thing' in repr(values['thing'])
+... assert values['thing'] is thing
+... assert values['other'] is other
+...
+All the 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()
+Caution
+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.
+It is also possible to stop all patches which have been started by using +patch.stopall.
+Stop all active patches. Only stops patches started with start.
+All of the patchers can be used as class decorators. When used in this way +they wrap every test method on the class. The patchers recognise methods that +start with test as being test methods. This is the same way that the +unittest.TestLoader finds test methods by default.
+It is possible that you want to use a different prefix for your tests. You can +inform the patchers of the different prefix by setting patch.TEST_PREFIX:
+>>> patch.TEST_PREFIX = 'foo'
+>>> value = 3
+>>>
+>>> @patch('__main__.value', 'not three')
+... class Thing(object):
+... def foo_one(self):
+... print value
+... def foo_two(self):
+... print value
+...
+>>>
+>>> Thing().foo_one()
+not three
+>>> Thing().foo_two()
+not three
+>>> value
+3
+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
+...
+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 looked up, 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:
+a.py
+ -> Defines SomeClass
+
+b.py
+ -> 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:
+++@patch(‘b.SomeClass’)
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:
+++@patch(‘a.SomeClass’)
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.
+Note
+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...
+