mock is a library for testing in Python. It allows you to replace parts of your system under test with mock objects. The main feature of mock is that it's simple to use, but mock also makes possible more complex mocking scenarios.
This is my philosophy of API design as it happens: simple things should be simple but complex things should be possible.
Several of these more complex scenarios are shown in the further examples section of the documentation. I've just updated one of these, the example of mocking properties.
Properties in Python are descriptors. When they are fetched from the class of an object they trigger code that is then executed. The code that is executed is the method that you have wrapped as the property getter.
Note that there is a special rule for attribute lookup on certain types of descriptors, which include properties. Even if an instance attribute exists, the class attribute will still be used instead. This is an exception to the normal attribute lookup rule that instance attributes are fetched in preference to class attributes. This is important because it means that when you want to mock a property you have to do it on the class and can't simply stick an attribute onto an object.
If you're using mock 0.7, with its support for magic methods, we can patch the property name and add a __get__ method to our mock. The presence of the __get__ method makes it a descriptor, so we can use it as a property:
>>> from mock import Mock, patch >>> class Foo(object): ... @property ... def fish(self): ... return 'fish' ... >>> with patch.object(Foo, 'fish') as mock_fish: ... mock_fish.__get__ = Mock(return_value='mocked fish') ... foo = Foo() ... print foo.fish ... mocked fish >>> mock_fish.__get__.assert_called_with(mock_fish, foo, Foo)
In this example mock_fish replaces the property and the mock we put in place of __get__ becomes the mocked getter method. As we're patching on the class this affects all instances of Foo.
There's no point in using MagicMock for this. MagicMock normallly makes using the Python protocol methods simpler by preconfiguring them. As you can see from the example above, mocking __get__ is supported but it isn't hooked up by default. It wouldn't be helpful if mocking any method on a class replaced it with a mock that acted as a descriptor, so if you want a mock to behave as a descriptor then you have to configure __get__, __set__ and __delete__ yourself.
Here's an alternative approach that works with all recent-ish versions of mock:
>>> from mock import Mock, patch >>> class PropertyMock(Mock): ... def __get__(self, instance, owner): ... return self() ... >>> prop_mock = PropertyMock() >>> with patch.object(Foo, 'fish', prop_mock): ... foo = Foo() ... prop_mock.return_value = 'mocked fish' ... print foo.fish ... mocked fish >>> prop_mock.assert_called_with()
As an added bonus, both of these examples work even if the Foo instance is created outside of the patch block. So long as the code using the property is executed whilst the patch is in place the attribute lookup will find our mocked version.