michael@0: .. _further-examples: michael@0: michael@0: ================== michael@0: Further Examples michael@0: ================== michael@0: michael@0: .. currentmodule:: mock michael@0: michael@0: .. testsetup:: michael@0: michael@0: from datetime import date michael@0: michael@0: BackendProvider = Mock() michael@0: sys.modules['mymodule'] = mymodule = Mock(name='mymodule') michael@0: michael@0: def grob(val): michael@0: "First frob and then clear val" michael@0: mymodule.frob(val) michael@0: val.clear() michael@0: michael@0: mymodule.frob = lambda val: val michael@0: mymodule.grob = grob michael@0: mymodule.date = date michael@0: michael@0: class TestCase(unittest2.TestCase): michael@0: def run(self): michael@0: result = unittest2.TestResult() michael@0: out = unittest2.TestCase.run(self, result) michael@0: assert result.wasSuccessful() michael@0: michael@0: from mock import inPy3k michael@0: michael@0: michael@0: michael@0: For comprehensive examples, see the unit tests included in the full source michael@0: distribution. michael@0: michael@0: Here are some more examples for some slightly more advanced scenarios than in michael@0: the :ref:`getting started ` guide. michael@0: michael@0: michael@0: Mocking chained calls michael@0: ===================== michael@0: michael@0: Mocking chained calls is actually straightforward with mock once you michael@0: understand the :attr:`~Mock.return_value` attribute. When a mock is called for michael@0: the first time, or you fetch its `return_value` before it has been called, a michael@0: new `Mock` is created. michael@0: michael@0: This means that you can see how the object returned from a call to a mocked michael@0: object has been used by interrogating the `return_value` mock: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock = Mock() michael@0: >>> mock().foo(a=2, b=3) michael@0: michael@0: >>> mock.return_value.foo.assert_called_with(a=2, b=3) michael@0: michael@0: From here it is a simple step to configure and then make assertions about michael@0: chained calls. Of course another alternative is writing your code in a more michael@0: testable way in the first place... michael@0: michael@0: So, suppose we have some code that looks a little bit like this: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class Something(object): michael@0: ... def __init__(self): michael@0: ... self.backend = BackendProvider() michael@0: ... def method(self): michael@0: ... response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call() michael@0: ... # more code michael@0: michael@0: Assuming that `BackendProvider` is already well tested, how do we test michael@0: `method()`? Specifically, we want to test that the code section `# more michael@0: code` uses the response object in the correct way. michael@0: michael@0: As this chain of calls is made from an instance attribute we can monkey patch michael@0: the `backend` attribute on a `Something` instance. In this particular case michael@0: we are only interested in the return value from the final call to michael@0: `start_call` so we don't have much configuration to do. Let's assume the michael@0: object it returns is 'file-like', so we'll ensure that our response object michael@0: uses the builtin `file` as its `spec`. michael@0: michael@0: To do this we create a mock instance as our mock backend and create a mock michael@0: response object for it. To set the response as the return value for that final michael@0: `start_call` we could do this: michael@0: michael@0: `mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response`. michael@0: michael@0: We can do that in a slightly nicer way using the :meth:`~Mock.configure_mock` michael@0: method to directly set the return value for us: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> something = Something() michael@0: >>> mock_response = Mock(spec=file) michael@0: >>> mock_backend = Mock() michael@0: >>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response} michael@0: >>> mock_backend.configure_mock(**config) michael@0: michael@0: With these we monkey patch the "mock backend" in place and can make the real michael@0: call: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> something.backend = mock_backend michael@0: >>> something.method() michael@0: michael@0: Using :attr:`~Mock.mock_calls` we can check the chained call with a single michael@0: assert. A chained call is several calls in one line of code, so there will be michael@0: several entries in `mock_calls`. We can use :meth:`call.call_list` to create michael@0: this list of calls for us: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call() michael@0: >>> call_list = chained.call_list() michael@0: >>> assert mock_backend.mock_calls == call_list michael@0: michael@0: michael@0: Partial mocking michael@0: =============== michael@0: michael@0: In some tests I wanted to mock out a call to `datetime.date.today() michael@0: `_ to return michael@0: a known date, but I didn't want to prevent the code under test from michael@0: creating new date objects. Unfortunately `datetime.date` is written in C, and michael@0: so I couldn't just monkey-patch out the static `date.today` method. michael@0: michael@0: I found a simple way of doing this that involved effectively wrapping the date michael@0: class with a mock, but passing through calls to the constructor to the real michael@0: class (and returning real instances). michael@0: michael@0: The :func:`patch decorator ` is used here to michael@0: mock out the `date` class in the module under test. The :attr:`side_effect` michael@0: attribute on the mock date class is then set to a lambda function that returns michael@0: a real date. When the mock date class is called a real date will be michael@0: constructed and returned by `side_effect`. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> from datetime import date michael@0: >>> with patch('mymodule.date') as mock_date: michael@0: ... mock_date.today.return_value = date(2010, 10, 8) michael@0: ... mock_date.side_effect = lambda *args, **kw: date(*args, **kw) michael@0: ... michael@0: ... assert mymodule.date.today() == date(2010, 10, 8) michael@0: ... assert mymodule.date(2009, 6, 8) == date(2009, 6, 8) michael@0: ... michael@0: michael@0: Note that we don't patch `datetime.date` globally, we patch `date` in the michael@0: module that *uses* it. See :ref:`where to patch `. michael@0: michael@0: When `date.today()` is called a known date is returned, but calls to the michael@0: `date(...)` constructor still return normal dates. Without this you can find michael@0: yourself having to calculate an expected result using exactly the same michael@0: algorithm as the code under test, which is a classic testing anti-pattern. michael@0: michael@0: Calls to the date constructor are recorded in the `mock_date` attributes michael@0: (`call_count` and friends) which may also be useful for your tests. michael@0: michael@0: An alternative way of dealing with mocking dates, or other builtin classes, michael@0: is discussed in `this blog entry michael@0: `_. michael@0: michael@0: michael@0: Mocking a Generator Method michael@0: ========================== michael@0: michael@0: A Python generator is a function or method that uses the `yield statement michael@0: `_ to michael@0: return a series of values when iterated over [#]_. michael@0: michael@0: A generator method / function is called to return the generator object. It is michael@0: the generator object that is then iterated over. The protocol method for michael@0: iteration is `__iter__ michael@0: `_, so we can michael@0: mock this using a `MagicMock`. michael@0: michael@0: Here's an example class with an "iter" method implemented as a generator: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class Foo(object): michael@0: ... def iter(self): michael@0: ... for i in [1, 2, 3]: michael@0: ... yield i michael@0: ... michael@0: >>> foo = Foo() michael@0: >>> list(foo.iter()) michael@0: [1, 2, 3] michael@0: michael@0: michael@0: How would we mock this class, and in particular its "iter" method? michael@0: michael@0: To configure the values returned from the iteration (implicit in the call to michael@0: `list`), we need to configure the object returned by the call to `foo.iter()`. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock_foo = MagicMock() michael@0: >>> mock_foo.iter.return_value = iter([1, 2, 3]) michael@0: >>> list(mock_foo.iter()) michael@0: [1, 2, 3] michael@0: michael@0: .. [#] There are also generator expressions and more `advanced uses michael@0: `_ of generators, but we aren't michael@0: concerned about them here. A very good introduction to generators and how michael@0: powerful they are is: `Generator Tricks for Systems Programmers michael@0: `_. michael@0: michael@0: michael@0: Applying the same patch to every test method michael@0: ============================================ michael@0: michael@0: If you want several patches in place for multiple test methods the obvious way michael@0: is to apply the patch decorators to every method. This can feel like unnecessary michael@0: repetition. For Python 2.6 or more recent you can use `patch` (in all its michael@0: various forms) as a class decorator. This applies the patches to all test michael@0: methods on the class. A test method is identified by methods whose names start michael@0: with `test`: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> @patch('mymodule.SomeClass') michael@0: ... class MyTest(TestCase): michael@0: ... michael@0: ... def test_one(self, MockSomeClass): michael@0: ... self.assertTrue(mymodule.SomeClass is MockSomeClass) michael@0: ... michael@0: ... def test_two(self, MockSomeClass): michael@0: ... self.assertTrue(mymodule.SomeClass is MockSomeClass) michael@0: ... michael@0: ... def not_a_test(self): michael@0: ... return 'something' michael@0: ... michael@0: >>> MyTest('test_one').test_one() michael@0: >>> MyTest('test_two').test_two() michael@0: >>> MyTest('test_two').not_a_test() michael@0: 'something' michael@0: michael@0: An alternative way of managing patches is to use the :ref:`start-and-stop`. michael@0: These allow you to move the patching into your `setUp` and `tearDown` methods. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class MyTest(TestCase): michael@0: ... def setUp(self): michael@0: ... self.patcher = patch('mymodule.foo') michael@0: ... self.mock_foo = self.patcher.start() michael@0: ... michael@0: ... def test_foo(self): michael@0: ... self.assertTrue(mymodule.foo is self.mock_foo) michael@0: ... michael@0: ... def tearDown(self): michael@0: ... self.patcher.stop() michael@0: ... michael@0: >>> MyTest('test_foo').run() michael@0: michael@0: If you use this technique you must ensure that the patching is "undone" by michael@0: calling `stop`. This can be fiddlier than you might think, because if an michael@0: exception is raised in the setUp then tearDown is not called. `unittest2 michael@0: `_ cleanup functions make this simpler: michael@0: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class MyTest(TestCase): michael@0: ... def setUp(self): michael@0: ... patcher = patch('mymodule.foo') michael@0: ... self.addCleanup(patcher.stop) michael@0: ... self.mock_foo = patcher.start() michael@0: ... michael@0: ... def test_foo(self): michael@0: ... self.assertTrue(mymodule.foo is self.mock_foo) michael@0: ... michael@0: >>> MyTest('test_foo').run() michael@0: michael@0: michael@0: Mocking Unbound Methods michael@0: ======================= michael@0: michael@0: Whilst writing tests today I needed to patch an *unbound method* (patching the michael@0: method on the class rather than on the instance). I needed self to be passed michael@0: in as the first argument because I want to make asserts about which objects michael@0: were calling this particular method. The issue is that you can't patch with a michael@0: mock for this, because if you replace an unbound method with a mock it doesn't michael@0: become a bound method when fetched from the instance, and so it doesn't get michael@0: self passed in. The workaround is to patch the unbound method with a real michael@0: function instead. The :func:`patch` decorator makes it so simple to michael@0: patch out methods with a mock that having to create a real function becomes a michael@0: nuisance. michael@0: michael@0: If you pass `autospec=True` to patch then it does the patching with a michael@0: *real* function object. This function object has the same signature as the one michael@0: it is replacing, but delegates to a mock under the hood. You still get your michael@0: mock auto-created in exactly the same way as before. What it means though, is michael@0: that if you use it to patch out an unbound method on a class the mocked michael@0: function will be turned into a bound method if it is fetched from an instance. michael@0: It will have `self` passed in as the first argument, which is exactly what I michael@0: wanted: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class Foo(object): michael@0: ... def foo(self): michael@0: ... pass michael@0: ... michael@0: >>> with patch.object(Foo, 'foo', autospec=True) as mock_foo: michael@0: ... mock_foo.return_value = 'foo' michael@0: ... foo = Foo() michael@0: ... foo.foo() michael@0: ... michael@0: 'foo' michael@0: >>> mock_foo.assert_called_once_with(foo) michael@0: michael@0: If we don't use `autospec=True` then the unbound method is patched out michael@0: with a Mock instance instead, and isn't called with `self`. michael@0: michael@0: michael@0: Checking multiple calls with mock michael@0: ================================= michael@0: michael@0: mock has a nice API for making assertions about how your mock objects are used. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock = Mock() michael@0: >>> mock.foo_bar.return_value = None michael@0: >>> mock.foo_bar('baz', spam='eggs') michael@0: >>> mock.foo_bar.assert_called_with('baz', spam='eggs') michael@0: michael@0: If your mock is only being called once you can use the michael@0: :meth:`assert_called_once_with` method that also asserts that the michael@0: :attr:`call_count` is one. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs') michael@0: >>> mock.foo_bar() michael@0: >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs') michael@0: Traceback (most recent call last): michael@0: ... michael@0: AssertionError: Expected to be called once. Called 2 times. michael@0: michael@0: Both `assert_called_with` and `assert_called_once_with` make assertions about michael@0: the *most recent* call. If your mock is going to be called several times, and michael@0: you want to make assertions about *all* those calls you can use michael@0: :attr:`~Mock.call_args_list`: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock = Mock(return_value=None) michael@0: >>> mock(1, 2, 3) michael@0: >>> mock(4, 5, 6) michael@0: >>> mock() michael@0: >>> mock.call_args_list michael@0: [call(1, 2, 3), call(4, 5, 6), call()] michael@0: michael@0: The :data:`call` helper makes it easy to make assertions about these calls. You michael@0: can build up a list of expected calls and compare it to `call_args_list`. This michael@0: looks remarkably similar to the repr of the `call_args_list`: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> expected = [call(1, 2, 3), call(4, 5, 6), call()] michael@0: >>> mock.call_args_list == expected michael@0: True michael@0: michael@0: michael@0: Coping with mutable arguments michael@0: ============================= michael@0: michael@0: Another situation is rare, but can bite you, is when your mock is called with michael@0: mutable arguments. `call_args` and `call_args_list` store *references* to the michael@0: arguments. If the arguments are mutated by the code under test then you can no michael@0: longer make assertions about what the values were when the mock was called. michael@0: michael@0: Here's some example code that shows the problem. Imagine the following functions michael@0: defined in 'mymodule':: michael@0: michael@0: def frob(val): michael@0: pass michael@0: michael@0: def grob(val): michael@0: "First frob and then clear val" michael@0: frob(val) michael@0: val.clear() michael@0: michael@0: When we try to test that `grob` calls `frob` with the correct argument look michael@0: what happens: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> with patch('mymodule.frob') as mock_frob: michael@0: ... val = set([6]) michael@0: ... mymodule.grob(val) michael@0: ... michael@0: >>> val michael@0: set([]) michael@0: >>> mock_frob.assert_called_with(set([6])) michael@0: Traceback (most recent call last): michael@0: ... michael@0: AssertionError: Expected: ((set([6]),), {}) michael@0: Called with: ((set([]),), {}) michael@0: michael@0: One possibility would be for mock to copy the arguments you pass in. This michael@0: could then cause problems if you do assertions that rely on object identity michael@0: for equality. michael@0: michael@0: Here's one solution that uses the :attr:`side_effect` michael@0: functionality. If you provide a `side_effect` function for a mock then michael@0: `side_effect` will be called with the same args as the mock. This gives us an michael@0: opportunity to copy the arguments and store them for later assertions. In this michael@0: example I'm using *another* mock to store the arguments so that I can use the michael@0: mock methods for doing the assertion. Again a helper function sets this up for michael@0: me. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> from copy import deepcopy michael@0: >>> from mock import Mock, patch, DEFAULT michael@0: >>> def copy_call_args(mock): michael@0: ... new_mock = Mock() michael@0: ... def side_effect(*args, **kwargs): michael@0: ... args = deepcopy(args) michael@0: ... kwargs = deepcopy(kwargs) michael@0: ... new_mock(*args, **kwargs) michael@0: ... return DEFAULT michael@0: ... mock.side_effect = side_effect michael@0: ... return new_mock michael@0: ... michael@0: >>> with patch('mymodule.frob') as mock_frob: michael@0: ... new_mock = copy_call_args(mock_frob) michael@0: ... val = set([6]) michael@0: ... mymodule.grob(val) michael@0: ... michael@0: >>> new_mock.assert_called_with(set([6])) michael@0: >>> new_mock.call_args michael@0: call(set([6])) michael@0: michael@0: `copy_call_args` is called with the mock that will be called. It returns a new michael@0: mock that we do the assertion on. The `side_effect` function makes a copy of michael@0: the args and calls our `new_mock` with the copy. michael@0: michael@0: .. note:: michael@0: michael@0: If your mock is only going to be used once there is an easier way of michael@0: checking arguments at the point they are called. You can simply do the michael@0: checking inside a `side_effect` function. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> def side_effect(arg): michael@0: ... assert arg == set([6]) michael@0: ... michael@0: >>> mock = Mock(side_effect=side_effect) michael@0: >>> mock(set([6])) michael@0: >>> mock(set()) michael@0: Traceback (most recent call last): michael@0: ... michael@0: AssertionError michael@0: michael@0: An alternative approach is to create a subclass of `Mock` or `MagicMock` that michael@0: copies (using `copy.deepcopy michael@0: `_) the arguments. michael@0: Here's an example implementation: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> from copy import deepcopy michael@0: >>> class CopyingMock(MagicMock): michael@0: ... def __call__(self, *args, **kwargs): michael@0: ... args = deepcopy(args) michael@0: ... kwargs = deepcopy(kwargs) michael@0: ... return super(CopyingMock, self).__call__(*args, **kwargs) michael@0: ... michael@0: >>> c = CopyingMock(return_value=None) michael@0: >>> arg = set() michael@0: >>> c(arg) michael@0: >>> arg.add(1) michael@0: >>> c.assert_called_with(set()) michael@0: >>> c.assert_called_with(arg) michael@0: Traceback (most recent call last): michael@0: ... michael@0: AssertionError: Expected call: mock(set([1])) michael@0: Actual call: mock(set([])) michael@0: >>> c.foo michael@0: michael@0: michael@0: When you subclass `Mock` or `MagicMock` all dynamically created attributes, michael@0: and the `return_value` will use your subclass automatically. That means all michael@0: children of a `CopyingMock` will also have the type `CopyingMock`. michael@0: michael@0: michael@0: Raising exceptions on attribute access michael@0: ====================================== michael@0: michael@0: You can use :class:`PropertyMock` to mimic the behaviour of properties. This michael@0: includes raising exceptions when an attribute is accessed. michael@0: michael@0: Here's an example raising a `ValueError` when the 'foo' attribute is accessed: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> m = MagicMock() michael@0: >>> p = PropertyMock(side_effect=ValueError) michael@0: >>> type(m).foo = p michael@0: >>> m.foo michael@0: Traceback (most recent call last): michael@0: .... michael@0: ValueError michael@0: michael@0: Because every mock object has its own type, a new subclass of whichever mock michael@0: class you're using, all mock objects are isolated from each other. You can michael@0: safely attach properties (or other descriptors or whatever you want in fact) michael@0: to `type(mock)` without affecting other mock objects. michael@0: michael@0: michael@0: Multiple calls with different effects michael@0: ===================================== michael@0: michael@0: .. note:: michael@0: michael@0: In mock 1.0 the handling of iterable `side_effect` was changed. Any michael@0: exceptions in the iterable will be raised instead of returned. michael@0: michael@0: Handling code that needs to behave differently on subsequent calls during the michael@0: test can be tricky. For example you may have a function that needs to raise michael@0: an exception the first time it is called but returns a response on the second michael@0: call (testing retry behaviour). michael@0: michael@0: One approach is to use a :attr:`side_effect` function that replaces itself. The michael@0: first time it is called the `side_effect` sets a new `side_effect` that will michael@0: be used for the second call. It then raises an exception: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> def side_effect(*args): michael@0: ... def second_call(*args): michael@0: ... return 'response' michael@0: ... mock.side_effect = second_call michael@0: ... raise Exception('boom') michael@0: ... michael@0: >>> mock = Mock(side_effect=side_effect) michael@0: >>> mock('first') michael@0: Traceback (most recent call last): michael@0: ... michael@0: Exception: boom michael@0: >>> mock('second') michael@0: 'response' michael@0: >>> mock.assert_called_with('second') michael@0: michael@0: Another perfectly valid way would be to pop return values from a list. If the michael@0: return value is an exception, raise it instead of returning it: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> returns = [Exception('boom'), 'response'] michael@0: >>> def side_effect(*args): michael@0: ... result = returns.pop(0) michael@0: ... if isinstance(result, Exception): michael@0: ... raise result michael@0: ... return result michael@0: ... michael@0: >>> mock = Mock(side_effect=side_effect) michael@0: >>> mock('first') michael@0: Traceback (most recent call last): michael@0: ... michael@0: Exception: boom michael@0: >>> mock('second') michael@0: 'response' michael@0: >>> mock.assert_called_with('second') michael@0: michael@0: Which approach you prefer is a matter of taste. The first approach is actually michael@0: a line shorter but maybe the second approach is more readable. michael@0: michael@0: michael@0: Nesting Patches michael@0: =============== michael@0: michael@0: Using patch as a context manager is nice, but if you do multiple patches you michael@0: can end up with nested with statements indenting further and further to the michael@0: right: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class MyTest(TestCase): michael@0: ... michael@0: ... def test_foo(self): michael@0: ... with patch('mymodule.Foo') as mock_foo: michael@0: ... with patch('mymodule.Bar') as mock_bar: michael@0: ... with patch('mymodule.Spam') as mock_spam: michael@0: ... assert mymodule.Foo is mock_foo michael@0: ... assert mymodule.Bar is mock_bar michael@0: ... assert mymodule.Spam is mock_spam michael@0: ... michael@0: >>> original = mymodule.Foo michael@0: >>> MyTest('test_foo').test_foo() michael@0: >>> assert mymodule.Foo is original michael@0: michael@0: With unittest2_ `cleanup` functions and the :ref:`start-and-stop` we can michael@0: achieve the same effect without the nested indentation. A simple helper michael@0: method, `create_patch`, puts the patch in place and returns the created mock michael@0: for us: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class MyTest(TestCase): michael@0: ... michael@0: ... def create_patch(self, name): michael@0: ... patcher = patch(name) michael@0: ... thing = patcher.start() michael@0: ... self.addCleanup(patcher.stop) michael@0: ... return thing michael@0: ... michael@0: ... def test_foo(self): michael@0: ... mock_foo = self.create_patch('mymodule.Foo') michael@0: ... mock_bar = self.create_patch('mymodule.Bar') michael@0: ... mock_spam = self.create_patch('mymodule.Spam') michael@0: ... michael@0: ... assert mymodule.Foo is mock_foo michael@0: ... assert mymodule.Bar is mock_bar michael@0: ... assert mymodule.Spam is mock_spam michael@0: ... michael@0: >>> original = mymodule.Foo michael@0: >>> MyTest('test_foo').run() michael@0: >>> assert mymodule.Foo is original michael@0: michael@0: michael@0: Mocking a dictionary with MagicMock michael@0: =================================== michael@0: michael@0: You may want to mock a dictionary, or other container object, recording all michael@0: access to it whilst having it still behave like a dictionary. michael@0: michael@0: We can do this with :class:`MagicMock`, which will behave like a dictionary, michael@0: and using :data:`~Mock.side_effect` to delegate dictionary access to a real michael@0: underlying dictionary that is under our control. michael@0: michael@0: When the `__getitem__` and `__setitem__` methods of our `MagicMock` are called michael@0: (normal dictionary access) then `side_effect` is called with the key (and in michael@0: the case of `__setitem__` the value too). We can also control what is returned. michael@0: michael@0: After the `MagicMock` has been used we can use attributes like michael@0: :data:`~Mock.call_args_list` to assert about how the dictionary was used: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> my_dict = {'a': 1, 'b': 2, 'c': 3} michael@0: >>> def getitem(name): michael@0: ... return my_dict[name] michael@0: ... michael@0: >>> def setitem(name, val): michael@0: ... my_dict[name] = val michael@0: ... michael@0: >>> mock = MagicMock() michael@0: >>> mock.__getitem__.side_effect = getitem michael@0: >>> mock.__setitem__.side_effect = setitem michael@0: michael@0: .. note:: michael@0: michael@0: An alternative to using `MagicMock` is to use `Mock` and *only* provide michael@0: the magic methods you specifically want: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock = Mock() michael@0: >>> mock.__setitem__ = Mock(side_effect=getitem) michael@0: >>> mock.__getitem__ = Mock(side_effect=setitem) michael@0: michael@0: A *third* option is to use `MagicMock` but passing in `dict` as the `spec` michael@0: (or `spec_set`) argument so that the `MagicMock` created only has michael@0: dictionary magic methods available: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock = MagicMock(spec_set=dict) michael@0: >>> mock.__getitem__.side_effect = getitem michael@0: >>> mock.__setitem__.side_effect = setitem michael@0: michael@0: With these side effect functions in place, the `mock` will behave like a normal michael@0: dictionary but recording the access. It even raises a `KeyError` if you try michael@0: to access a key that doesn't exist. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock['a'] michael@0: 1 michael@0: >>> mock['c'] michael@0: 3 michael@0: >>> mock['d'] michael@0: Traceback (most recent call last): michael@0: ... michael@0: KeyError: 'd' michael@0: >>> mock['b'] = 'fish' michael@0: >>> mock['d'] = 'eggs' michael@0: >>> mock['b'] michael@0: 'fish' michael@0: >>> mock['d'] michael@0: 'eggs' michael@0: michael@0: After it has been used you can make assertions about the access using the normal michael@0: mock methods and attributes: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock.__getitem__.call_args_list michael@0: [call('a'), call('c'), call('d'), call('b'), call('d')] michael@0: >>> mock.__setitem__.call_args_list michael@0: [call('b', 'fish'), call('d', 'eggs')] michael@0: >>> my_dict michael@0: {'a': 1, 'c': 3, 'b': 'fish', 'd': 'eggs'} michael@0: michael@0: michael@0: Mock subclasses and their attributes michael@0: ==================================== michael@0: michael@0: There are various reasons why you might want to subclass `Mock`. One reason michael@0: might be to add helper methods. Here's a silly example: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class MyMock(MagicMock): michael@0: ... def has_been_called(self): michael@0: ... return self.called michael@0: ... michael@0: >>> mymock = MyMock(return_value=None) michael@0: >>> mymock michael@0: michael@0: >>> mymock.has_been_called() michael@0: False michael@0: >>> mymock() michael@0: >>> mymock.has_been_called() michael@0: True michael@0: michael@0: The standard behaviour for `Mock` instances is that attributes and the return michael@0: value mocks are of the same type as the mock they are accessed on. This ensures michael@0: that `Mock` attributes are `Mocks` and `MagicMock` attributes are `MagicMocks` michael@0: [#]_. So if you're subclassing to add helper methods then they'll also be michael@0: available on the attributes and return value mock of instances of your michael@0: subclass. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mymock.foo michael@0: michael@0: >>> mymock.foo.has_been_called() michael@0: False michael@0: >>> mymock.foo() michael@0: michael@0: >>> mymock.foo.has_been_called() michael@0: True michael@0: michael@0: Sometimes this is inconvenient. For example, `one user michael@0: `_ is subclassing mock to michael@0: created a `Twisted adaptor michael@0: `_. michael@0: Having this applied to attributes too actually causes errors. michael@0: michael@0: `Mock` (in all its flavours) uses a method called `_get_child_mock` to create michael@0: these "sub-mocks" for attributes and return values. You can prevent your michael@0: subclass being used for attributes by overriding this method. The signature is michael@0: that it takes arbitrary keyword arguments (`**kwargs`) which are then passed michael@0: onto the mock constructor: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class Subclass(MagicMock): michael@0: ... def _get_child_mock(self, **kwargs): michael@0: ... return MagicMock(**kwargs) michael@0: ... michael@0: >>> mymock = Subclass() michael@0: >>> mymock.foo michael@0: michael@0: >>> assert isinstance(mymock, Subclass) michael@0: >>> assert not isinstance(mymock.foo, Subclass) michael@0: >>> assert not isinstance(mymock(), Subclass) michael@0: michael@0: .. [#] An exception to this rule are the non-callable mocks. Attributes use the michael@0: callable variant because otherwise non-callable mocks couldn't have callable michael@0: methods. michael@0: michael@0: michael@0: Mocking imports with patch.dict michael@0: =============================== michael@0: michael@0: One situation where mocking can be hard is where you have a local import inside michael@0: a function. These are harder to mock because they aren't using an object from michael@0: the module namespace that we can patch out. michael@0: michael@0: Generally local imports are to be avoided. They are sometimes done to prevent michael@0: circular dependencies, for which there is *usually* a much better way to solve michael@0: the problem (refactor the code) or to prevent "up front costs" by delaying the michael@0: import. This can also be solved in better ways than an unconditional local michael@0: import (store the module as a class or module attribute and only do the import michael@0: on first use). michael@0: michael@0: That aside there is a way to use `mock` to affect the results of an import. michael@0: Importing fetches an *object* from the `sys.modules` dictionary. Note that it michael@0: fetches an *object*, which need not be a module. Importing a module for the michael@0: first time results in a module object being put in `sys.modules`, so usually michael@0: when you import something you get a module back. This need not be the case michael@0: however. michael@0: michael@0: This means you can use :func:`patch.dict` to *temporarily* put a mock in place michael@0: in `sys.modules`. Any imports whilst this patch is active will fetch the mock. michael@0: When the patch is complete (the decorated function exits, the with statement michael@0: body is complete or `patcher.stop()` is called) then whatever was there michael@0: previously will be restored safely. michael@0: michael@0: Here's an example that mocks out the 'fooble' module. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock = Mock() michael@0: >>> with patch.dict('sys.modules', {'fooble': mock}): michael@0: ... import fooble michael@0: ... fooble.blob() michael@0: ... michael@0: michael@0: >>> assert 'fooble' not in sys.modules michael@0: >>> mock.blob.assert_called_once_with() michael@0: michael@0: As you can see the `import fooble` succeeds, but on exit there is no 'fooble' michael@0: left in `sys.modules`. michael@0: michael@0: This also works for the `from module import name` form: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock = Mock() michael@0: >>> with patch.dict('sys.modules', {'fooble': mock}): michael@0: ... from fooble import blob michael@0: ... blob.blip() michael@0: ... michael@0: michael@0: >>> mock.blob.blip.assert_called_once_with() michael@0: michael@0: With slightly more work you can also mock package imports: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> mock = Mock() michael@0: >>> modules = {'package': mock, 'package.module': mock.module} michael@0: >>> with patch.dict('sys.modules', modules): michael@0: ... from package.module import fooble michael@0: ... fooble() michael@0: ... michael@0: michael@0: >>> mock.module.fooble.assert_called_once_with() michael@0: michael@0: michael@0: Tracking order of calls and less verbose call assertions michael@0: ======================================================== michael@0: michael@0: The :class:`Mock` class allows you to track the *order* of method calls on michael@0: your mock objects through the :attr:`~Mock.method_calls` attribute. This michael@0: doesn't allow you to track the order of calls between separate mock objects, michael@0: however we can use :attr:`~Mock.mock_calls` to achieve the same effect. michael@0: michael@0: Because mocks track calls to child mocks in `mock_calls`, and accessing an michael@0: arbitrary attribute of a mock creates a child mock, we can create our separate michael@0: mocks from a parent one. Calls to those child mock will then all be recorded, michael@0: in order, in the `mock_calls` of the parent: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> manager = Mock() michael@0: >>> mock_foo = manager.foo michael@0: >>> mock_bar = manager.bar michael@0: michael@0: >>> mock_foo.something() michael@0: michael@0: >>> mock_bar.other.thing() michael@0: michael@0: michael@0: >>> manager.mock_calls michael@0: [call.foo.something(), call.bar.other.thing()] michael@0: michael@0: We can then assert about the calls, including the order, by comparing with michael@0: the `mock_calls` attribute on the manager mock: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> expected_calls = [call.foo.something(), call.bar.other.thing()] michael@0: >>> manager.mock_calls == expected_calls michael@0: True michael@0: michael@0: If `patch` is creating, and putting in place, your mocks then you can attach michael@0: them to a manager mock using the :meth:`~Mock.attach_mock` method. After michael@0: attaching calls will be recorded in `mock_calls` of the manager. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> manager = MagicMock() michael@0: >>> with patch('mymodule.Class1') as MockClass1: michael@0: ... with patch('mymodule.Class2') as MockClass2: michael@0: ... manager.attach_mock(MockClass1, 'MockClass1') michael@0: ... manager.attach_mock(MockClass2, 'MockClass2') michael@0: ... MockClass1().foo() michael@0: ... MockClass2().bar() michael@0: ... michael@0: michael@0: michael@0: >>> manager.mock_calls michael@0: [call.MockClass1(), michael@0: call.MockClass1().foo(), michael@0: call.MockClass2(), michael@0: call.MockClass2().bar()] michael@0: michael@0: If many calls have been made, but you're only interested in a particular michael@0: sequence of them then an alternative is to use the michael@0: :meth:`~Mock.assert_has_calls` method. This takes a list of calls (constructed michael@0: with the :data:`call` object). If that sequence of calls are in michael@0: :attr:`~Mock.mock_calls` then the assert succeeds. michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> m = MagicMock() michael@0: >>> m().foo().bar().baz() michael@0: michael@0: >>> m.one().two().three() michael@0: michael@0: >>> calls = call.one().two().three().call_list() michael@0: >>> m.assert_has_calls(calls) michael@0: michael@0: Even though the chained call `m.one().two().three()` aren't the only calls that michael@0: have been made to the mock, the assert still succeeds. michael@0: michael@0: Sometimes a mock may have several calls made to it, and you are only interested michael@0: in asserting about *some* of those calls. You may not even care about the michael@0: order. In this case you can pass `any_order=True` to `assert_has_calls`: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> m = MagicMock() michael@0: >>> m(1), m.two(2, 3), m.seven(7), m.fifty('50') michael@0: (...) michael@0: >>> calls = [call.fifty('50'), call(1), call.seven(7)] michael@0: >>> m.assert_has_calls(calls, any_order=True) michael@0: michael@0: michael@0: More complex argument matching michael@0: ============================== michael@0: michael@0: Using the same basic concept as `ANY` we can implement matchers to do more michael@0: complex assertions on objects used as arguments to mocks. michael@0: michael@0: Suppose we expect some object to be passed to a mock that by default michael@0: compares equal based on object identity (which is the Python default for user michael@0: defined classes). To use :meth:`~Mock.assert_called_with` we would need to pass michael@0: in the exact same object. If we are only interested in some of the attributes michael@0: of this object then we can create a matcher that will check these attributes michael@0: for us. michael@0: michael@0: You can see in this example how a 'standard' call to `assert_called_with` isn't michael@0: sufficient: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class Foo(object): michael@0: ... def __init__(self, a, b): michael@0: ... self.a, self.b = a, b michael@0: ... michael@0: >>> mock = Mock(return_value=None) michael@0: >>> mock(Foo(1, 2)) michael@0: >>> mock.assert_called_with(Foo(1, 2)) michael@0: Traceback (most recent call last): michael@0: ... michael@0: AssertionError: Expected: call(<__main__.Foo object at 0x...>) michael@0: Actual call: call(<__main__.Foo object at 0x...>) michael@0: michael@0: A comparison function for our `Foo` class might look something like this: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> def compare(self, other): michael@0: ... if not type(self) == type(other): michael@0: ... return False michael@0: ... if self.a != other.a: michael@0: ... return False michael@0: ... if self.b != other.b: michael@0: ... return False michael@0: ... return True michael@0: ... michael@0: michael@0: And a matcher object that can use comparison functions like this for its michael@0: equality operation would look something like this: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> class Matcher(object): michael@0: ... def __init__(self, compare, some_obj): michael@0: ... self.compare = compare michael@0: ... self.some_obj = some_obj michael@0: ... def __eq__(self, other): michael@0: ... return self.compare(self.some_obj, other) michael@0: ... michael@0: michael@0: Putting all this together: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> match_foo = Matcher(compare, Foo(1, 2)) michael@0: >>> mock.assert_called_with(match_foo) michael@0: michael@0: The `Matcher` is instantiated with our compare function and the `Foo` object michael@0: we want to compare against. In `assert_called_with` the `Matcher` equality michael@0: method will be called, which compares the object the mock was called with michael@0: against the one we created our matcher with. If they match then michael@0: `assert_called_with` passes, and if they don't an `AssertionError` is raised: michael@0: michael@0: .. doctest:: michael@0: michael@0: >>> match_wrong = Matcher(compare, Foo(3, 4)) michael@0: >>> mock.assert_called_with(match_wrong) michael@0: Traceback (most recent call last): michael@0: ... michael@0: AssertionError: Expected: ((,), {}) michael@0: Called with: ((,), {}) michael@0: michael@0: With a bit of tweaking you could have the comparison function raise the michael@0: `AssertionError` directly and provide a more useful failure message. michael@0: michael@0: As of version 1.5, the Python testing library `PyHamcrest michael@0: `_ provides similar functionality, michael@0: that may be useful here, in the form of its equality matcher michael@0: (`hamcrest.library.integration.match_equality michael@0: `_). michael@0: michael@0: michael@0: Less verbose configuration of mock objects michael@0: ========================================== michael@0: michael@0: This recipe, for easier configuration of mock objects, is now part of `Mock`. michael@0: See the :meth:`~Mock.configure_mock` method. michael@0: michael@0: michael@0: Matching any argument in assertions michael@0: =================================== michael@0: michael@0: This example is now built in to mock. See :data:`ANY`. michael@0: michael@0: michael@0: Mocking Properties michael@0: ================== michael@0: michael@0: This example is now built in to mock. See :class:`PropertyMock`. michael@0: michael@0: michael@0: Mocking open michael@0: ============ michael@0: michael@0: This example is now built in to mock. See :func:`mock_open`. michael@0: michael@0: michael@0: Mocks without some attributes michael@0: ============================= michael@0: michael@0: This example is now built in to mock. See :ref:`deleting-attributes`.