Mock Patching Methods¶

Common uses forMock objects include:

• Patching methods

• Recording method calls on objects

You might want to replace a method on an object to check thatit is called with the correct arguments by another part of the system:

>>>real=SomeClass()>>>real.method=MagicMock(name='method')>>>real.method(3,4,5,key='value')<MagicMock name='method()' id='...'>

Once our mock has been used (real.method in this example) it has methodsand attributes that allow you to make assertions about how it has been used.

Once the mock has been called itscalled attribute is set toTrue. More importantly we can use theassert_called_with() orassert_called_once_with() method to check that it was called withthe correct arguments.

This example tests that callingProductionClass().method results in a call tothesomething method:

>>>classProductionClass:...defmethod(self):...self.something(1,2,3)...defsomething(self,a,b,c):...pass...>>>real=ProductionClass()>>>real.something=MagicMock()>>>real.method()>>>real.something.assert_called_once_with(1,2,3)

Mock for Method Calls on an Object¶

In the last example we patched a method directly on an object to check that itwas called correctly. Another common use case is to pass an object into amethod (or some part of the system under test) and then check that it is usedin the correct way.

The simpleProductionClass below has acloser method. If it is called withan object then it callsclose on it.

>>>classProductionClass:...defcloser(self,something):...something.close()...

So to test it we need to pass in an object with aclose method and checkthat it was called correctly.

>>>real=ProductionClass()>>>mock=Mock()>>>real.closer(mock)>>>mock.close.assert_called_with()

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 thenaccessing it in the test will create it, butassert_called_with()will raise a failure exception.

Mocking Classes¶

A common use case is to mock out classes instantiated by your code under test.When you patch a class, then that class is replaced with a mock. Instancesare created bycalling the class. This means you access the «mock instance»by looking at the return value of the mocked class.

In the example below we have a functionsome_function that instantiatesFooand calls a method on it. The call topatch() replaces the classFoo with amock. TheFoo instance is the result of calling the mock, so it is configuredby modifying the mockreturn_value.

>>>defsome_function():...instance=module.Foo()...returninstance.method()...>>>withpatch('module.Foo')asmock:...instance=mock.return_value...instance.method.return_value='the result'...result=some_function()...assertresult=='the result'

Naming your mocks¶

It can be useful to give your mocks a name. The name is shown in the repr ofthe mock and can be helpful when the mock appears in test failure messages. Thename is also propagated to attributes or methods of the mock:

>>>mock=MagicMock(name='foo')>>>mock<MagicMock name='foo' id='...'>>>>mock.method<MagicMock name='foo.method' id='...'>

Tracking all Calls¶

Often you want to track more than a single call to a method. Themock_calls attribute records all callsto child attributes of the mock - and also to their children.

>>>mock=MagicMock()>>>mock.method()<MagicMock name='mock.method()' id='...'>>>>mock.attribute.method(10,x=53)<MagicMock name='mock.attribute.method()' id='...'>>>>mock.mock_calls[call.method(), call.attribute.method(10, x=53)]

If you make an assertion aboutmock_calls and any unexpected methodshave been called, then the assertion will fail. This is useful because as wellas asserting that the calls you expected have been made, you are also checkingthat they were made in the right order and with no additional calls:

You use thecall object to construct lists for comparing withmock_calls:

>>>expected=[call.method(),call.attribute.method(10,x=53)]>>>mock.mock_calls==expectedTrue

However, parameters to calls that return mocks are not recorded, which means it is notpossible to track nested calls where the parameters used to create ancestors are important:

>>>m=Mock()>>>m.factory(important=True).deliver()<Mock name='mock.factory().deliver()' id='...'>>>>m.mock_calls[-1]==call.factory(important=False).deliver()True

Setting Return Values and Attributes¶

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

>>>mock=Mock()>>>mock.return_value=3>>>mock()3

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

>>>mock=Mock()>>>mock.method.return_value=3>>>mock.method()3

The return value can also be set in the constructor:

>>>mock=Mock(return_value=3)>>>mock()3

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

>>>mock=Mock()>>>mock.x=3>>>mock.x3

Sometimes you want to mock up a more complex situation, like for examplemock.connection.cursor().execute("SELECT1"). If we wanted this call toreturn a list, then we have to configure the result of the nested call.

We can usecall to construct the set of calls in a «chained call» likethis for easy assertion afterwards:

>>>mock=Mock()>>>cursor=mock.connection.cursor.return_value>>>cursor.execute.return_value=['foo']>>>mock.connection.cursor().execute("SELECT 1")['foo']>>>expected=call.connection.cursor().execute("SELECT 1").call_list()>>>mock.mock_calls[call.connection.cursor(), call.connection.cursor().execute('SELECT 1')]>>>mock.mock_calls==expectedTrue

It is the call to.call_list() that turns our call object into a list ofcalls representing the chained calls.

Raising exceptions with mocks¶

A useful attribute isside_effect. If you set this to anexception class or instance then the exception will be raised when the mockis called.

>>>mock=Mock(side_effect=Exception('Boom!'))>>>mock()Traceback (most recent call last):...Exception:Boom!

Side effect functions and iterables¶

side_effect can also be set to a function or an iterable. The use case forside_effect as an iterable is where your mock is going to be called severaltimes, and you want each call to return a different value. When you setside_effect to an iterable every call to the mock returns the next valuefrom the iterable:

>>>mock=MagicMock(side_effect=[4,5,6])>>>mock()4>>>mock()5>>>mock()6

For more advanced use cases, like dynamically varying the return valuesdepending on what the mock is called with,side_effect can be a function.The function will be called with the same arguments as the mock. Whatever thefunction returns is what the call returns:

>>>vals={(1,2):1,(2,3):2}>>>defside_effect(*args):...returnvals[args]...>>>mock=MagicMock(side_effect=side_effect)>>>mock(1,2)1>>>mock(2,3)2

Mocking asynchronous iterators¶

Since Python 3.8,AsyncMock andMagicMock have support to mockAsynchronous Iterators through__aiter__. Thereturn_valueattribute of__aiter__ can be used to set the return values to be used foriteration.

>>>mock=MagicMock()# AsyncMock also works here>>>mock.__aiter__.return_value=[1,2,3]>>>asyncdefmain():...return[iasyncforiinmock]...>>>asyncio.run(main())[1, 2, 3]

Mocking asynchronous context manager¶

Since Python 3.8,AsyncMock andMagicMock have support to mockAsynchronous Context Managers through__aenter__ and__aexit__.By default,__aenter__ and__aexit__ areAsyncMock instances thatreturn an async function.

>>>classAsyncContextManager:...asyncdef__aenter__(self):...returnself...asyncdef__aexit__(self,exc_type,exc,tb):...pass...>>>mock_instance=MagicMock(AsyncContextManager())# AsyncMock also works here>>>asyncdefmain():...asyncwithmock_instanceasresult:...pass...>>>asyncio.run(main())>>>mock_instance.__aenter__.assert_awaited_once()>>>mock_instance.__aexit__.assert_awaited_once()

Creating a Mock from an Existing Object¶

One problem with over use of mocking is that it couples your tests to theimplementation of your mocks rather than your real code. Suppose you have aclass that implementssome_method. In a test for another class, youprovide a mock of this object thatalso providessome_method. If lateryou refactor the first class, so that it no longer hassome_method - thenyour 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 thespec keyword argument. Accessing methods / attributes on themock that don’t exist on your specification object will immediately raise anattribute error. If you change the implementation of your specification, thentests that use that class will start failing immediately without you having toinstantiate the class in those tests.

>>>mock=Mock(spec=SomeClass)>>>mock.old_method()Traceback (most recent call last):...AttributeError:Mock object has no attribute 'old_method'. Did you mean: 'class_method'?

Using a specification also enables a smarter matching of calls made to themock, regardless of whether some parameters were passed as positional ornamed arguments:

>>>deff(a,b,c):pass...>>>mock=Mock(spec=f)>>>mock(1,2,3)<Mock name='mock()' id='140161580456576'>>>>mock.assert_called_with(a=1,b=2,c=3)

If you want this smarter matching to also work with method calls on the mock,you can useauto-speccing.

If you want a stronger form of specification that prevents the settingof arbitrary attributes as well as the getting of them then you can usespec_set instead ofspec.

Using side_effect to return per file content¶

mock_open() is used to patchopen() method.side_effectcan be used to return a new Mock object per call. This can be used to return differentcontents per file stored in a dictionary:

DEFAULT="default"data_dict={"file1":"data1","file2":"data2"}defopen_side_effect(name):returnmock_open(read_data=data_dict.get(name,DEFAULT))()withpatch("builtins.open",side_effect=open_side_effect):withopen("file1")asfile1:assertfile1.read()=="data1"withopen("file2")asfile2:assertfile2.read()=="data2"withopen("file3")asfile2:assertfile2.read()=="default"

Mocking chained calls¶

Mocking chained calls is actually straightforward with mock once youunderstand thereturn_value attribute. When a mock is called forthe first time, or you fetch itsreturn_value before it has been called, anewMock is created.

This means that you can see how the object returned from a call to a mockedobject has been used by interrogating thereturn_value mock:

>>>mock=Mock()>>>mock().foo(a=2,b=3)<Mock name='mock().foo()' id='...'>>>>mock.return_value.foo.assert_called_with(a=2,b=3)

From here it is a simple step to configure and then make assertions aboutchained calls. Of course another alternative is writing your code in a moretestable way in the first place…

So, suppose we have some code that looks a little bit like this:

>>>classSomething:...def__init__(self):...self.backend=BackendProvider()...defmethod(self):...response=self.backend.get_endpoint('foobar').create_call('spam','eggs').start_call()...# more code

Assuming thatBackendProvider is already well tested, how do we testmethod()? Specifically, we want to test that the code section#morecode uses the response object in the correct way.

As this chain of calls is made from an instance attribute we can monkey patchthebackend attribute on aSomething instance. In this particular casewe are only interested in the return value from the final call tostart_call so we don’t have much configuration to do. Let’s assume theobject it returns is “file-like”, so we’ll ensure that our response objectuses the builtinopen() as itsspec.

To do this we create a mock instance as our mock backend and create a mockresponse object for it. To set the response as the return value for that finalstart_call we could do this:

mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value=mock_response

We can do that in a slightly nicer way using theconfigure_mock()method to directly set the return value for us:

>>>something=Something()>>>mock_response=Mock(spec=open)>>>mock_backend=Mock()>>>config={'get_endpoint.return_value.create_call.return_value.start_call.return_value':mock_response}>>>mock_backend.configure_mock(**config)

With these we monkey patch the «mock backend» in place and can make the realcall:

>>>something.backend=mock_backend>>>something.method()

Usingmock_calls we can check the chained call with a singleassert. A chained call is several calls in one line of code, so there will beseveral entries inmock_calls. We can usecall.call_list() to createthis list of calls for us:

>>>chained=call.get_endpoint('foobar').create_call('spam','eggs').start_call()>>>call_list=chained.call_list()>>>assertmock_backend.mock_calls==call_list

Partial mocking¶

In some tests I wanted to mock out a call todatetime.date.today()to return a known date, but I didn’t want to prevent the code under test fromcreating new date objects. Unfortunatelydatetime.date is written in C, andso I couldn’t just monkey-patch out the staticdatetime.date.today() method.

I found a simple way of doing this that involved effectively wrapping the dateclass with a mock, but passing through calls to the constructor to the realclass (and returning real instances).

Thepatchdecorator is used here tomock out thedate class in the module under test. Theside_effectattribute on the mock date class is then set to a lambda function that returnsa real date. When the mock date class is called a real date will beconstructed and returned byside_effect.

>>>fromdatetimeimportdate>>>withpatch('mymodule.date')asmock_date:...mock_date.today.return_value=date(2010,10,8)...mock_date.side_effect=lambda*args,**kw:date(*args,**kw)......assertmymodule.date.today()==date(2010,10,8)...assertmymodule.date(2009,6,8)==date(2009,6,8)

Note that we don’t patchdatetime.date globally, we patchdate in themodule thatuses it. Seewhere to patch.

Whendate.today() is called a known date is returned, but calls to thedate(...) constructor still return normal dates. Without this you can findyourself having to calculate an expected result using exactly the samealgorithm as the code under test, which is a classic testing anti-pattern.

Calls to the date constructor are recorded in themock_date attributes(call_count and friends) which may also be useful for your tests.

An alternative way of dealing with mocking dates, or other builtin classes,is discussed inthis blog entry.

Mocking a Generator Method¶

A Python generator is a function or method that uses theyield statementto return a series of values when iterated over[1].

A generator method / function is called to return the generator object. It isthe generator object that is then iterated over. The protocol method foriteration is__iter__(), so we canmock this using aMagicMock.

Here’s an example class with an «iter» method implemented as a generator:

>>>classFoo:...defiter(self):...foriin[1,2,3]:...yieldi...>>>foo=Foo()>>>list(foo.iter())[1, 2, 3]

How would we mock this class, and in particular its «iter» method?

To configure the values returned from the iteration (implicit in the call tolist), we need to configure the object returned by the call tofoo.iter().

>>>mock_foo=MagicMock()>>>mock_foo.iter.return_value=iter([1,2,3])>>>list(mock_foo.iter())[1, 2, 3]

There are also generator expressions and moreadvanced uses of generators, but we aren’tconcerned about them here. A very good introduction to generators and howpowerful they are is:Generator Tricks for Systems Programmers.

Applying the same patch to every test method¶

If you want several patches in place for multiple test methods the obvious wayis to apply the patch decorators to every method. This can feel like unnecessaryrepetition. Instead, you can usepatch() (in all itsvarious forms) as a class decorator. This applies the patches to all testmethods on the class. A test method is identified by methods whose names startwithtest:

>>>@patch('mymodule.SomeClass')...classMyTest(unittest.TestCase):......deftest_one(self,MockSomeClass):...self.assertIs(mymodule.SomeClass,MockSomeClass)......deftest_two(self,MockSomeClass):...self.assertIs(mymodule.SomeClass,MockSomeClass)......defnot_a_test(self):...return'something'...>>>MyTest('test_one').test_one()>>>MyTest('test_two').test_two()>>>MyTest('test_two').not_a_test()'something'

An alternative way of managing patches is to use thepatch methods: start and stop.These allow you to move the patching into yoursetUp andtearDown methods.

>>>classMyTest(unittest.TestCase):...defsetUp(self):...self.patcher=patch('mymodule.foo')...self.mock_foo=self.patcher.start()......deftest_foo(self):...self.assertIs(mymodule.foo,self.mock_foo)......deftearDown(self):...self.patcher.stop()...>>>MyTest('test_foo').run()

If you use this technique you must ensure that the patching is «undone» bycallingstop. This can be fiddlier than you might think, because if anexception is raised in the setUp then tearDown is not called.unittest.TestCase.addCleanup() makes this easier:

>>>classMyTest(unittest.TestCase):...defsetUp(self):...patcher=patch('mymodule.foo')...self.addCleanup(patcher.stop)...self.mock_foo=patcher.start()......deftest_foo(self):...self.assertIs(mymodule.foo,self.mock_foo)...>>>MyTest('test_foo').run()

Mocking Unbound Methods¶

Whilst writing tests today I needed to patch anunbound method (patching themethod on the class rather than on the instance). I needed self to be passedin as the first argument because I want to make asserts about which objectswere calling this particular method. The issue is that you can’t patch with amock for this, because if you replace an unbound method with a mock it doesn’tbecome a bound method when fetched from the instance, and so it doesn’t getself passed in. The workaround is to patch the unbound method with a realfunction instead. Thepatch() decorator makes it so simple topatch out methods with a mock that having to create a real function becomes anuisance.

If you passautospec=True to patch then it does the patching with areal function object. This function object has the same signature as the oneit is replacing, but delegates to a mock under the hood. You still get yourmock auto-created in exactly the same way as before. What it means though, isthat if you use it to patch out an unbound method on a class the mockedfunction will be turned into a bound method if it is fetched from an instance.It will haveself passed in as the first argument, which is exactly what Iwanted:

>>>classFoo:...deffoo(self):...pass...>>>withpatch.object(Foo,'foo',autospec=True)asmock_foo:...mock_foo.return_value='foo'...foo=Foo()...foo.foo()...'foo'>>>mock_foo.assert_called_once_with(foo)

If we don’t useautospec=True then the unbound method is patched outwith a Mock instance instead, and isn’t called withself.

Checking multiple calls with mock¶

mock has a nice API for making assertions about how your mock objects are used.

>>>mock=Mock()>>>mock.foo_bar.return_value=None>>>mock.foo_bar('baz',spam='eggs')>>>mock.foo_bar.assert_called_with('baz',spam='eggs')

If your mock is only being called once you can use theassert_called_once_with() method that also asserts that thecall_count is one.

>>>mock.foo_bar.assert_called_once_with('baz',spam='eggs')>>>mock.foo_bar()>>>mock.foo_bar.assert_called_once_with('baz',spam='eggs')Traceback (most recent call last):...AssertionError:Expected 'foo_bar' to be called once. Called 2 times.Calls: [call('baz', spam='eggs'), call()].

Bothassert_called_with andassert_called_once_with make assertions aboutthemost recent call. If your mock is going to be called several times, andyou want to make assertions aboutall those calls you can usecall_args_list:

>>>mock=Mock(return_value=None)>>>mock(1,2,3)>>>mock(4,5,6)>>>mock()>>>mock.call_args_list[call(1, 2, 3), call(4, 5, 6), call()]

Thecall helper makes it easy to make assertions about these calls. Youcan build up a list of expected calls and compare it tocall_args_list. Thislooks remarkably similar to the repr of thecall_args_list:

>>>expected=[call(1,2,3),call(4,5,6),call()]>>>mock.call_args_list==expectedTrue

Coping with mutable arguments¶

Another situation is rare, but can bite you, is when your mock is called withmutable arguments.call_args andcall_args_list storereferences to thearguments. If the arguments are mutated by the code under test then you can nolonger make assertions about what the values were when the mock was called.

Here’s some example code that shows the problem. Imagine the following functionsdefined in “mymodule”:

deffrob(val):passdefgrob(val):"First frob and then clear val"frob(val)val.clear()

When we try to test thatgrob callsfrob with the correct argument lookwhat happens:

>>>withpatch('mymodule.frob')asmock_frob:...val={6}...mymodule.grob(val)...>>>valset()>>>mock_frob.assert_called_with({6})Traceback (most recent call last):...AssertionError:Expected: (({6},), {})Called with: ((set(),), {})

One possibility would be for mock to copy the arguments you pass in. Thiscould then cause problems if you do assertions that rely on object identityfor equality.

Here’s one solution that uses theside_effectfunctionality. If you provide aside_effect function for a mock thenside_effect will be called with the same args as the mock. This gives us anopportunity to copy the arguments and store them for later assertions. In thisexample I’m usinganother mock to store the arguments so that I can use themock methods for doing the assertion. Again a helper function sets this up forme.

>>>fromcopyimportdeepcopy>>>fromunittest.mockimportMock,patch,DEFAULT>>>defcopy_call_args(mock):...new_mock=Mock()...defside_effect(*args,**kwargs):...args=deepcopy(args)...kwargs=deepcopy(kwargs)...new_mock(*args,**kwargs)...returnDEFAULT...mock.side_effect=side_effect...returnnew_mock...>>>withpatch('mymodule.frob')asmock_frob:...new_mock=copy_call_args(mock_frob)...val={6}...mymodule.grob(val)...>>>new_mock.assert_called_with({6})>>>new_mock.call_argscall({6})

copy_call_args is called with the mock that will be called. It returns a newmock that we do the assertion on. Theside_effect function makes a copy ofthe args and calls ournew_mock with the copy.

>>>defside_effect(arg):...assertarg=={6}...>>>mock=Mock(side_effect=side_effect)>>>mock({6})>>>mock(set())Traceback (most recent call last):...AssertionError

An alternative approach is to create a subclass ofMock orMagicMock that copies (usingcopy.deepcopy()) the arguments.Here’s an example implementation:

>>>fromcopyimportdeepcopy>>>classCopyingMock(MagicMock):...def__call__(self,/,*args,**kwargs):...args=deepcopy(args)...kwargs=deepcopy(kwargs)...returnsuper().__call__(*args,**kwargs)...>>>c=CopyingMock(return_value=None)>>>arg=set()>>>c(arg)>>>arg.add(1)>>>c.assert_called_with(set())>>>c.assert_called_with(arg)Traceback (most recent call last):...AssertionError:expected call not found.Expected: mock({1})Actual: mock(set())>>>c.foo<CopyingMock name='mock.foo' id='...'>

When you subclassMock orMagicMock all dynamically created attributes,and thereturn_value will use your subclass automatically. That means allchildren of aCopyingMock will also have the typeCopyingMock.

Nesting Patches¶

Using patch as a context manager is nice, but if you do multiple patches youcan end up with nested with statements indenting further and further to theright:

>>>classMyTest(unittest.TestCase):......deftest_foo(self):...withpatch('mymodule.Foo')asmock_foo:...withpatch('mymodule.Bar')asmock_bar:...withpatch('mymodule.Spam')asmock_spam:...assertmymodule.Fooismock_foo...assertmymodule.Barismock_bar...assertmymodule.Spamismock_spam...>>>original=mymodule.Foo>>>MyTest('test_foo').test_foo()>>>assertmymodule.Fooisoriginal

With unittestcleanup functions and thepatch methods: start and stop we canachieve the same effect without the nested indentation. A simple helpermethod,create_patch, puts the patch in place and returns the created mockfor us:

>>>classMyTest(unittest.TestCase):......defcreate_patch(self,name):...patcher=patch(name)...thing=patcher.start()...self.addCleanup(patcher.stop)...returnthing......deftest_foo(self):...mock_foo=self.create_patch('mymodule.Foo')...mock_bar=self.create_patch('mymodule.Bar')...mock_spam=self.create_patch('mymodule.Spam')......assertmymodule.Fooismock_foo...assertmymodule.Barismock_bar...assertmymodule.Spamismock_spam...>>>original=mymodule.Foo>>>MyTest('test_foo').run()>>>assertmymodule.Fooisoriginal

Mocking a dictionary with MagicMock¶

You may want to mock a dictionary, or other container object, recording allaccess to it whilst having it still behave like a dictionary.

We can do this withMagicMock, which will behave like a dictionary,and usingside_effect to delegate dictionary access to a realunderlying dictionary that is under our control.

When the__getitem__() and__setitem__() methodsof ourMagicMock are called(normal dictionary access) thenside_effect is called with the key (and inthe case of__setitem__ the value too). We can also control what is returned.

After theMagicMock has been used we can use attributes likecall_args_list to assert about how the dictionary was used:

>>>my_dict={'a':1,'b':2,'c':3}>>>defgetitem(name):...returnmy_dict[name]...>>>defsetitem(name,val):...my_dict[name]=val...>>>mock=MagicMock()>>>mock.__getitem__.side_effect=getitem>>>mock.__setitem__.side_effect=setitem

>>>mock=Mock()>>>mock.__getitem__=Mock(side_effect=getitem)>>>mock.__setitem__=Mock(side_effect=setitem)

>>>mock=MagicMock(spec_set=dict)>>>mock.__getitem__.side_effect=getitem>>>mock.__setitem__.side_effect=setitem

With these side effect functions in place, themock will behave like a normaldictionary but recording the access. It even raises aKeyError if you tryto access a key that doesn’t exist.

>>>mock['a']1>>>mock['c']3>>>mock['d']Traceback (most recent call last):...KeyError:'d'>>>mock['b']='fish'>>>mock['d']='eggs'>>>mock['b']'fish'>>>mock['d']'eggs'

After it has been used you can make assertions about the access using the normalmock methods and attributes:

>>>mock.__getitem__.call_args_list[call('a'), call('c'), call('d'), call('b'), call('d')]>>>mock.__setitem__.call_args_list[call('b', 'fish'), call('d', 'eggs')]>>>my_dict{'a': 1, 'b': 'fish', 'c': 3, 'd': 'eggs'}

Mock subclasses and their attributes¶

There are various reasons why you might want to subclassMock. Onereason might be to add helper methods. Here’s a silly example:

>>>classMyMock(MagicMock):...defhas_been_called(self):...returnself.called...>>>mymock=MyMock(return_value=None)>>>mymock<MyMock id='...'>>>>mymock.has_been_called()False>>>mymock()>>>mymock.has_been_called()True

The standard behaviour forMock instances is that attributes and the returnvalue mocks are of the same type as the mock they are accessed on. This ensuresthatMock attributes areMocks andMagicMock attributes areMagicMocks[2]. So if you’re subclassing to add helper methods then they’ll also beavailable on the attributes and return value mock of instances of yoursubclass.

>>>mymock.foo<MyMock name='mock.foo' id='...'>>>>mymock.foo.has_been_called()False>>>mymock.foo()<MyMock name='mock.foo()' id='...'>>>>mymock.foo.has_been_called()True

Sometimes this is inconvenient. For example,one user is subclassing mock tocreated aTwisted adaptor.Having this applied to attributes too actually causes errors.

Mock (in all its flavours) uses a method called_get_child_mock to createthese «sub-mocks» for attributes and return values. You can prevent yoursubclass being used for attributes by overriding this method. The signature isthat it takes arbitrary keyword arguments (**kwargs) which are then passedonto the mock constructor:

>>>classSubclass(MagicMock):...def_get_child_mock(self,/,**kwargs):...returnMagicMock(**kwargs)...>>>mymock=Subclass()>>>mymock.foo<MagicMock name='mock.foo' id='...'>>>>assertisinstance(mymock,Subclass)>>>assertnotisinstance(mymock.foo,Subclass)>>>assertnotisinstance(mymock(),Subclass)

An exception to this rule are the non-callable mocks. Attributes use thecallable variant because otherwise non-callable mocks couldn’t have callablemethods.

Mocking imports with patch.dict¶

One situation where mocking can be hard is where you have a local import insidea function. These are harder to mock because they aren’t using an object fromthe module namespace that we can patch out.

Generally local imports are to be avoided. They are sometimes done to preventcircular dependencies, for which there isusually a much better way to solvethe problem (refactor the code) or to prevent «up front costs» by delaying theimport. This can also be solved in better ways than an unconditional localimport (store the module as a class or module attribute and only do the importon first use).

That aside there is a way to usemock to affect the results of an import.Importing fetches anobject from thesys.modules dictionary. Note that itfetches anobject, which need not be a module. Importing a module for thefirst time results in a module object being put insys.modules, so usuallywhen you import something you get a module back. This need not be the casehowever.

This means you can usepatch.dict() totemporarily put a mock in placeinsys.modules. Any imports whilst this patch is active will fetch the mock.When the patch is complete (the decorated function exits, the with statementbody is complete orpatcher.stop() is called) then whatever was therepreviously will be restored safely.

Here’s an example that mocks out the “fooble” module.

>>>importsys>>>mock=Mock()>>>withpatch.dict('sys.modules',{'fooble':mock}):...importfooble...fooble.blob()...<Mock name='mock.blob()' id='...'>>>>assert'fooble'notinsys.modules>>>mock.blob.assert_called_once_with()

As you can see theimportfooble succeeds, but on exit there is no “fooble”left insys.modules.

This also works for thefrommoduleimportname form:

>>>mock=Mock()>>>withpatch.dict('sys.modules',{'fooble':mock}):...fromfoobleimportblob...blob.blip()...<Mock name='mock.blob.blip()' id='...'>>>>mock.blob.blip.assert_called_once_with()

With slightly more work you can also mock package imports:

>>>mock=Mock()>>>modules={'package':mock,'package.module':mock.module}>>>withpatch.dict('sys.modules',modules):...frompackage.moduleimportfooble...fooble()...<Mock name='mock.module.fooble()' id='...'>>>>mock.module.fooble.assert_called_once_with()

Tracking order of calls and less verbose call assertions¶

TheMock class allows you to track theorder of method calls onyour mock objects through themethod_calls attribute. Thisdoesn’t allow you to track the order of calls between separate mock objects,however we can usemock_calls to achieve the same effect.

Because mocks track calls to child mocks inmock_calls, and accessing anarbitrary attribute of a mock creates a child mock, we can create our separatemocks from a parent one. Calls to those child mock will then all be recorded,in order, in themock_calls of the parent:

>>>manager=Mock()>>>mock_foo=manager.foo>>>mock_bar=manager.bar

>>>mock_foo.something()<Mock name='mock.foo.something()' id='...'>>>>mock_bar.other.thing()<Mock name='mock.bar.other.thing()' id='...'>

>>>manager.mock_calls[call.foo.something(), call.bar.other.thing()]

We can then assert about the calls, including the order, by comparing withthemock_calls attribute on the manager mock:

>>>expected_calls=[call.foo.something(),call.bar.other.thing()]>>>manager.mock_calls==expected_callsTrue

Ifpatch is creating, and putting in place, your mocks then you can attachthem to a manager mock using theattach_mock() method. Afterattaching calls will be recorded inmock_calls of the manager.

>>>manager=MagicMock()>>>withpatch('mymodule.Class1')asMockClass1:...withpatch('mymodule.Class2')asMockClass2:...manager.attach_mock(MockClass1,'MockClass1')...manager.attach_mock(MockClass2,'MockClass2')...MockClass1().foo()...MockClass2().bar()<MagicMock name='mock.MockClass1().foo()' id='...'><MagicMock name='mock.MockClass2().bar()' id='...'>>>>manager.mock_calls[call.MockClass1(),call.MockClass1().foo(),call.MockClass2(),call.MockClass2().bar()]

If many calls have been made, but you’re only interested in a particularsequence of them then an alternative is to use theassert_has_calls() method. This takes a list of calls (constructedwith thecall object). If that sequence of calls are inmock_calls then the assert succeeds.

>>>m=MagicMock()>>>m().foo().bar().baz()<MagicMock name='mock().foo().bar().baz()' id='...'>>>>m.one().two().three()<MagicMock name='mock.one().two().three()' id='...'>>>>calls=call.one().two().three().call_list()>>>m.assert_has_calls(calls)

Even though the chained callm.one().two().three() aren’t the only calls thathave been made to the mock, the assert still succeeds.

Sometimes a mock may have several calls made to it, and you are only interestedin asserting aboutsome of those calls. You may not even care about theorder. In this case you can passany_order=True toassert_has_calls:

>>>m=MagicMock()>>>m(1),m.two(2,3),m.seven(7),m.fifty('50')(...)>>>calls=[call.fifty('50'),call(1),call.seven(7)]>>>m.assert_has_calls(calls,any_order=True)

More complex argument matching¶

Using the same basic concept asANY we can implement matchers to do morecomplex assertions on objects used as arguments to mocks.

Suppose we expect some object to be passed to a mock that by defaultcompares equal based on object identity (which is the Python default for userdefined classes). To useassert_called_with() we would need to passin the exact same object. If we are only interested in some of the attributesof this object then we can create a matcher that will check these attributesfor us.

You can see in this example how a “standard” call toassert_called_with isn’tsufficient:

>>>classFoo:...def__init__(self,a,b):...self.a,self.b=a,b...>>>mock=Mock(return_value=None)>>>mock(Foo(1,2))>>>mock.assert_called_with(Foo(1,2))Traceback (most recent call last):...AssertionError:expected call not found.Expected: mock(<__main__.Foo object at 0x...>)Actual: mock(<__main__.Foo object at 0x...>)

A comparison function for ourFoo class might look something like this:

>>>defcompare(self,other):...ifnottype(self)==type(other):...returnFalse...ifself.a!=other.a:...returnFalse...ifself.b!=other.b:...returnFalse...returnTrue...

And a matcher object that can use comparison functions like this for itsequality operation would look something like this:

>>>classMatcher:...def__init__(self,compare,some_obj):...self.compare=compare...self.some_obj=some_obj...def__eq__(self,other):...returnself.compare(self.some_obj,other)...

Putting all this together:

>>>match_foo=Matcher(compare,Foo(1,2))>>>mock.assert_called_with(match_foo)

TheMatcher is instantiated with our compare function and theFoo objectwe want to compare against. Inassert_called_with theMatcher equalitymethod will be called, which compares the object the mock was called withagainst the one we created our matcher with. If they match thenassert_called_with passes, and if they don’t anAssertionError is raised:

>>>match_wrong=Matcher(compare,Foo(3,4))>>>mock.assert_called_with(match_wrong)Traceback (most recent call last):...AssertionError:Expected: ((<Matcher object at 0x...>,), {})Called with: ((<Foo object at 0x...>,), {})

With a bit of tweaking you could have the comparison function raise theAssertionError directly and provide a more useful failure message.

As of version 1.5, the Python testing libraryPyHamcrest provides similar functionality,that may be useful here, in the form of its equality matcher(hamcrest.library.integration.match_equality).