Quick Guide¶

Mock andMagicMock objects create all attributes andmethods as you access them and store details of how they have been used. Youcan configure them, to specify return values or limit what attributes areavailable, and then make assertions about how they have been used:

>>>fromunittest.mockimportMagicMock>>>thing=ProductionClass()>>>thing.method=MagicMock(return_value=3)>>>thing.method(3,4,5,key='value')3>>>thing.method.assert_called_with(3,4,5,key='value')

side_effect allows you to perform side effects, including raising anexception when a mock is called:

>>>fromunittest.mockimportMock>>>mock=Mock(side_effect=KeyError('foo'))>>>mock()Traceback (most recent call last):...KeyError:'foo'

>>>values={'a':1,'b':2,'c':3}>>>defside_effect(arg):...returnvalues[arg]...>>>mock.side_effect=side_effect>>>mock('a'),mock('b'),mock('c')(1, 2, 3)>>>mock.side_effect=[5,4,3,2,1]>>>mock(),mock(),mock()(5, 4, 3)

Mock has many other ways you can configure it and control its behaviour. Forexample thespec argument configures the mock to take its specificationfrom another object. Attempting to access attributes or methods on the mockthat don’t exist on the spec will fail with anAttributeError.

Thepatch() decorator / context manager makes it easy to mock classes orobjects in a module under test. The object you specify will be replaced with amock (or other object) during the test and restored when the test ends:

>>>fromunittest.mockimportpatch>>>@patch('module.ClassName2')...@patch('module.ClassName1')...deftest(MockClass1,MockClass2):...module.ClassName1()...module.ClassName2()...assertMockClass1ismodule.ClassName1...assertMockClass2ismodule.ClassName2...assertMockClass1.called...assertMockClass2.called...>>>test()

As well as a decoratorpatch() can be used as a context manager in a withstatement:

>>>withpatch.object(ProductionClass,'method',return_value=None)asmock_method:...thing=ProductionClass()...thing.method(1,2,3)...>>>mock_method.assert_called_once_with(1,2,3)

There is alsopatch.dict() for setting values in a dictionary justduring a scope and restoring the dictionary to its original state when the testends:

>>>foo={'key':'value'}>>>original=foo.copy()>>>withpatch.dict(foo,{'newkey':'newvalue'},clear=True):...assertfoo=={'newkey':'newvalue'}...>>>assertfoo==original

Mock supports the mocking of Pythonmagic methods. Theeasiest way of using magic methods is with theMagicMock class. Itallows you to do things like:

>>>mock=MagicMock()>>>mock.__str__.return_value='foobarbaz'>>>str(mock)'foobarbaz'>>>mock.__str__.assert_called_with()

Mock allows you to assign functions (or other Mock instances) to magic methodsand they will be called appropriately. TheMagicMock class is just a Mockvariant that has all of the magic methods pre-created for you (well, all theuseful ones anyway).

The following is an example of using magic methods with the ordinary Mockclass:

>>>mock=Mock()>>>mock.__str__=Mock(return_value='wheeeeee')>>>str(mock)'wheeeeee'

For ensuring that the mock objects in your tests have the same api as theobjects they are replacing, you can useauto-speccing.Auto-speccing can be done through theautospec argument to patch, or thecreate_autospec() function. Auto-speccing creates mock objects thathave the same attributes and methods as the objects they are replacing, andany functions and methods (including constructors) have the same callsignature as the real object.

This ensures that your mocks will fail in the same way as your productioncode if they are used incorrectly:

>>>fromunittest.mockimportcreate_autospec>>>deffunction(a,b,c):...pass...>>>mock_function=create_autospec(function,return_value='fishy')>>>mock_function(1,2,3)'fishy'>>>mock_function.assert_called_once_with(1,2,3)>>>mock_function('wrong arguments')Traceback (most recent call last):...TypeError:missing a required argument: 'b'

create_autospec() can also be used on classes, where it copies the signature ofthe__init__ method, and on callable objects where it copies the signature ofthe__call__ method.

The Mock Class¶

Mock is a flexible mock object intended to replace the use of stubs andtest doubles throughout your code. Mocks are callable and create attributes asnew mocks when you access them[1]. Accessing the same attribute will alwaysreturn the same mock. Mocks record how you use them, allowing you to makeassertions about what your code has done to them.

MagicMock is a subclass ofMock with all the magic methodspre-created and ready to use. There are also non-callable variants, usefulwhen you are mocking out objects that aren’t callable:NonCallableMock andNonCallableMagicMock

Thepatch() decorators makes it easy to temporarily replace classesin a particular module with aMock object. By defaultpatch() will createaMagicMock for you. You can specify an alternative class ofMock usingthenew_callable argument topatch().

classunittest.mock.Mock(spec=None,side_effect=None,return_value=DEFAULT,wraps=None,name=None,spec_set=None,unsafe=False,**kwargs)¶

Create a newMock object.Mock takes several optional argumentsthat specify the behaviour of the Mock object:

• spec: This can be either a list of strings or an existing object (aclass or instance) that acts as the specification for the mock object. Ifyou pass in an object then a list of strings is formed by calling dir onthe object (excluding unsupported magic attributes and methods).Accessing any attribute not in this list will raise anAttributeError.

  Ifspec is an object (rather than a list of strings) then__class__ returns the class of the spec object. Thisallows mocks to passisinstance() tests.

• spec_set: A stricter variant ofspec. If used, attempting tosetor get an attribute on the mock that isn’t on the object passed asspec_set will raise anAttributeError.

• side_effect: A function to be called whenever the Mock is called. Seetheside_effect attribute. Useful for raising exceptions ordynamically changing return values. The function is called with the samearguments as the mock, and unless it returnsDEFAULT, the returnvalue of this function is used as the return value.

  Alternativelyside_effect can be an exception class or instance. Inthis case the exception will be raised when the mock is called.

  Ifside_effect is an iterable then each call to the mock will returnthe next value from the iterable.

  Aside_effect can be cleared by setting it toNone.

• return_value: The value returned when the mock is called. By defaultthis is a new Mock (created on first access). See thereturn_value attribute.

• unsafe: By default, accessing any attribute whose name starts withassert,assret,asert,aseert orassrt will raise anAttributeError. Passingunsafe=True will allow access tothese attributes.

  Added in version 3.5.

• wraps: Item for the mock object to wrap. Ifwraps is notNone thencalling the Mock will pass the call through to the wrapped object(returning the real result). Attribute access on the mock will return aMock object that wraps the corresponding attribute of the wrappedobject (so attempting to access an attribute that doesn’t exist willraise anAttributeError).

  If the mock has an explicitreturn_value set then calls are not passedto the wrapped object and thereturn_value is returned instead.

• name: If the mock has a name then it will be used in the repr of themock. This can be useful for debugging. The name is propagated to childmocks.

Mocks can also be called with arbitrary keyword arguments. These will beused to set attributes on the mock after it is created. See theconfigure_mock() method for details.

assert_called()¶

Assert that the mock was called at least once.

>>>mock=Mock()>>>mock.method()<Mock name='mock.method()' id='...'>>>>mock.method.assert_called()

Added in version 3.6.

assert_called_once()¶

Assert that the mock was called exactly once.

>>>mock=Mock()>>>mock.method()<Mock name='mock.method()' id='...'>>>>mock.method.assert_called_once()>>>mock.method()<Mock name='mock.method()' id='...'>>>>mock.method.assert_called_once()Traceback (most recent call last):...AssertionError:Expected 'method' to have been called once. Called 2 times.Calls: [call(), call()].

Added in version 3.6.

assert_called_with(*args,**kwargs)¶

This method is a convenient way of asserting that the last call has beenmade in a particular way:

>>>mock=Mock()>>>mock.method(1,2,3,test='wow')<Mock name='mock.method()' id='...'>>>>mock.method.assert_called_with(1,2,3,test='wow')

assert_called_once_with(*args,**kwargs)¶

Assert that the mock was called exactly once and that call was with thespecified arguments.

>>>mock=Mock(return_value=None)>>>mock('foo',bar='baz')>>>mock.assert_called_once_with('foo',bar='baz')>>>mock('other',bar='values')>>>mock.assert_called_once_with('other',bar='values')Traceback (most recent call last):...AssertionError:Expected 'mock' to be called once. Called 2 times.Calls: [call('foo', bar='baz'), call('other', bar='values')].

assert_any_call(*args,**kwargs)¶

assert the mock has been called with the specified arguments.

The assert passes if the mock hasever been called, unlikeassert_called_with() andassert_called_once_with() thatonly pass if the call is the most recent one, and in the case ofassert_called_once_with() it must also be the only call.

>>>mock=Mock(return_value=None)>>>mock(1,2,arg='thing')>>>mock('some','thing','else')>>>mock.assert_any_call(1,2,arg='thing')

assert_has_calls(calls,any_order=False)¶

assert the mock has been called with the specified calls.Themock_calls list is checked for the calls.

Ifany_order is false then the calls must besequential. There can be extra calls before or after thespecified calls.

Ifany_order is true then the calls can be in any order, butthey must all appear inmock_calls.

>>>mock=Mock(return_value=None)>>>mock(1)>>>mock(2)>>>mock(3)>>>mock(4)>>>calls=[call(2),call(3)]>>>mock.assert_has_calls(calls)>>>calls=[call(4),call(2),call(3)]>>>mock.assert_has_calls(calls,any_order=True)

assert_not_called()¶

Assert the mock was never called.

>>>m=Mock()>>>m.hello.assert_not_called()>>>obj=m.hello()>>>m.hello.assert_not_called()Traceback (most recent call last):...AssertionError:Expected 'hello' to not have been called. Called 1 times.Calls: [call()].

Added in version 3.5.

reset_mock(*,return_value=False,side_effect=False)¶

The reset_mock method resets all the call attributes on a mock object:

>>>mock=Mock(return_value=None)>>>mock('hello')>>>mock.calledTrue>>>mock.reset_mock()>>>mock.calledFalse

This can be useful where you want to make a series of assertions thatreuse the same object.

return_value parameter when set toTrue resetsreturn_value:

>>>mock=Mock(return_value=5)>>>mock('hello')5>>>mock.reset_mock(return_value=True)>>>mock('hello')<Mock name='mock()' id='...'>

side_effect parameter when set toTrue resetsside_effect:

>>>mock=Mock(side_effect=ValueError)>>>mock('hello')Traceback (most recent call last):...ValueError>>>mock.reset_mock(side_effect=True)>>>mock('hello')<Mock name='mock()' id='...'>

Note thatreset_mock()doesn’t clear thereturn_value,side_effect or any child attributes you haveset using normal assignment by default.

Child mocks are reset as well.

Changed in version 3.6:Added two keyword-only arguments to the reset_mock function.

mock_add_spec(spec,spec_set=False)¶

Add a spec to a mock.spec can either be an object or alist of strings. Only attributes on thespec can be fetched asattributes from the mock.

Ifspec_set is true then only attributes on the spec can be set.

attach_mock(mock,attribute)¶

Attach a mock as an attribute of this one, replacing its name andparent. Calls to the attached mock will be recorded in themethod_calls andmock_calls attributes of this one.

configure_mock(**kwargs)¶

Set attributes on the mock through keyword arguments.

Attributes plus return values and side effects can be set on childmocks using standard dot notation and unpacking a dictionary in themethod call:

>>>mock=Mock()>>>attrs={'method.return_value':3,'other.side_effect':KeyError}>>>mock.configure_mock(**attrs)>>>mock.method()3>>>mock.other()Traceback (most recent call last):...KeyError

The same thing can be achieved in the constructor call to mocks:

>>>attrs={'method.return_value':3,'other.side_effect':KeyError}>>>mock=Mock(some_attribute='eggs',**attrs)>>>mock.some_attribute'eggs'>>>mock.method()3>>>mock.other()Traceback (most recent call last):...KeyError

configure_mock() exists to make it easier to do configurationafter the mock has been created.

__dir__()¶

Mock objects limit the results ofdir(some_mock) to useful results.For mocks with aspec this includes all the permitted attributesfor the mock.

SeeFILTER_DIR for what this filtering does, and how toswitch it off.

_get_child_mock(**kw)¶

Create the child mocks for attributes and return value.By default child mocks will be the same type as the parent.Subclasses of Mock may want to override this to customize the waychild mocks are made.

For non-callable mocks the callable variant will be used (rather thanany custom subclass).

called¶

A boolean representing whether or not the mock object has been called:

>>>mock=Mock(return_value=None)>>>mock.calledFalse>>>mock()>>>mock.calledTrue

call_count¶

An integer telling you how many times the mock object has been called:

>>>mock=Mock(return_value=None)>>>mock.call_count0>>>mock()>>>mock()>>>mock.call_count2

return_value¶

Set this to configure the value returned by calling the mock:

>>>mock=Mock()>>>mock.return_value='fish'>>>mock()'fish'

The default return value is a mock object and you can configure it inthe normal way:

>>>mock=Mock()>>>mock.return_value.attribute=sentinel.Attribute>>>mock.return_value()<Mock name='mock()()' id='...'>>>>mock.return_value.assert_called_with()

return_value can also be set in the constructor:

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

side_effect¶

This can either be a function to be called when the mock is called,an iterable or an exception (class or instance) to be raised.

If you pass in a function it will be called with same arguments as themock and unless the function returns theDEFAULT singleton thecall to the mock will then return whatever the function returns. If thefunction returnsDEFAULT then the mock will return its normalvalue (from thereturn_value).

If you pass in an iterable, it is used to retrieve an iterator whichmust yield a value on every call. This value can either be an exceptioninstance to be raised, or a value to be returned from the call to themock (DEFAULT handling is identical to the function case).

An example of a mock that raises an exception (to test exceptionhandling of an API):

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

Usingside_effect to return a sequence of values:

>>>mock=Mock()>>>mock.side_effect=[3,2,1]>>>mock(),mock(),mock()(3, 2, 1)

Using a callable:

>>>mock=Mock(return_value=3)>>>defside_effect(*args,**kwargs):...returnDEFAULT...>>>mock.side_effect=side_effect>>>mock()3

side_effect can be set in the constructor. Here’s an example thatadds one to the value the mock is called with and returns it:

>>>side_effect=lambdavalue:value+1>>>mock=Mock(side_effect=side_effect)>>>mock(3)4>>>mock(-8)-7

Settingside_effect toNone clears it:

>>>m=Mock(side_effect=KeyError,return_value=3)>>>m()Traceback (most recent call last):...KeyError>>>m.side_effect=None>>>m()3

call_args¶

This is eitherNone (if the mock hasn’t been called), or thearguments that the mock was last called with. This will be in theform of a tuple: the first member, which can also be accessed throughtheargs property, is any ordered arguments the mock wascalled with (or an empty tuple) and the second member, which canalso be accessed through thekwargs property, is any keywordarguments (or an empty dictionary).

>>>mock=Mock(return_value=None)>>>print(mock.call_args)None>>>mock()>>>mock.call_argscall()>>>mock.call_args==()True>>>mock(3,4)>>>mock.call_argscall(3, 4)>>>mock.call_args==((3,4),)True>>>mock.call_args.args(3, 4)>>>mock.call_args.kwargs{}>>>mock(3,4,5,key='fish',next='w00t!')>>>mock.call_argscall(3, 4, 5, key='fish', next='w00t!')>>>mock.call_args.args(3, 4, 5)>>>mock.call_args.kwargs{'key': 'fish', 'next': 'w00t!'}

call_args, along with members of the listscall_args_list,method_calls andmock_calls arecall objects.These are tuples, so they can be unpacked to get at the individualarguments and make more complex assertions. Seecalls as tuples.

Changed in version 3.8:Addedargs andkwargs properties.

call_args_list¶

This is a list of all the calls made to the mock object in sequence(so the length of the list is the number of times it has beencalled). Before any calls have been made it is an empty list. Thecall object can be used for conveniently constructing lists ofcalls to compare withcall_args_list.

>>>mock=Mock(return_value=None)>>>mock()>>>mock(3,4)>>>mock(key='fish',next='w00t!')>>>mock.call_args_list[call(), call(3, 4), call(key='fish', next='w00t!')]>>>expected=[(),((3,4),),({'key':'fish','next':'w00t!'},)]>>>mock.call_args_list==expectedTrue

Members ofcall_args_list arecall objects. These can beunpacked as tuples to get at the individual arguments. Seecalls as tuples.

method_calls¶

As well as tracking calls to themselves, mocks also track calls tomethods and attributes, andtheir methods and attributes:

>>>mock=Mock()>>>mock.method()<Mock name='mock.method()' id='...'>>>>mock.property.method.attribute()<Mock name='mock.property.method.attribute()' id='...'>>>>mock.method_calls[call.method(), call.property.method.attribute()]

Members ofmethod_calls arecall objects. These can beunpacked as tuples to get at the individual arguments. Seecalls as tuples.

mock_calls¶

mock_calls recordsall calls to the mock object, its methods,magic methodsand return value mocks.

>>>mock=MagicMock()>>>result=mock(1,2,3)>>>mock.first(a=3)<MagicMock name='mock.first()' id='...'>>>>mock.second()<MagicMock name='mock.second()' id='...'>>>>int(mock)1>>>result(1)<MagicMock name='mock()()' id='...'>>>>expected=[call(1,2,3),call.first(a=3),call.second(),...call.__int__(),call()(1)]>>>mock.mock_calls==expectedTrue

Members ofmock_calls arecall objects. These can beunpacked as tuples to get at the individual arguments. Seecalls as tuples.

Note

The waymock_calls are recorded means that where nestedcalls are made, the parameters of ancestor calls are not recordedand so will always compare equal:

>>>mock=MagicMock()>>>mock.top(a=3).bottom()<MagicMock name='mock.top().bottom()' id='...'>>>>mock.mock_calls[call.top(a=3), call.top().bottom()]>>>mock.mock_calls[-1]==call.top(a=-1).bottom()True

__class__¶

Normally the__class__ attribute of an object will return its type.For a mock object with aspec,__class__ returns the spec classinstead. This allows mock objects to passisinstance() tests for theobject they are replacing / masquerading as:

>>>mock=Mock(spec=3)>>>isinstance(mock,int)True

__class__ is assignable to, this allows a mock to pass anisinstance() check without forcing you to use a spec:

>>>mock=Mock()>>>mock.__class__=dict>>>isinstance(mock,dict)True

classunittest.mock.NonCallableMock(spec=None,wraps=None,name=None,spec_set=None,**kwargs)¶

A non-callable version ofMock. The constructor parameters have the samemeaning ofMock, with the exception ofreturn_value andside_effectwhich have no meaning on a non-callable mock.

Mock objects that use a class or an instance as aspec orspec_set are able to passisinstance() tests:

>>>mock=Mock(spec=SomeClass)>>>isinstance(mock,SomeClass)True>>>mock=Mock(spec_set=SomeClass())>>>isinstance(mock,SomeClass)True

TheMock classes have support for mocking magic methods. Seemagicmethods for the full details.

The mock classes and thepatch() decorators all take arbitrary keywordarguments for configuration. For thepatch() decorators the keywords arepassed to the constructor of the mock being created. The keyword argumentsare for configuring attributes of the mock:

>>>m=MagicMock(attribute=3,other='fish')>>>m.attribute3>>>m.other'fish'

The return value and side effect of child mocks can be set in the same way,using dotted notation. As you can’t use dotted names directly in a call youhave to create a dictionary and unpack it using**:

>>>attrs={'method.return_value':3,'other.side_effect':KeyError}>>>mock=Mock(some_attribute='eggs',**attrs)>>>mock.some_attribute'eggs'>>>mock.method()3>>>mock.other()Traceback (most recent call last):...KeyError

A callable mock which was created with aspec (or aspec_set) willintrospect the specification object’s signature when matching calls tothe mock. Therefore, it can match the actual call’s arguments regardlessof whether they were passed positionally or by name:

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

This applies toassert_called_with(),assert_called_once_with(),assert_has_calls() andassert_any_call(). WhenAutospeccing, it will alsoapply to method calls on the mock object.

classunittest.mock.PropertyMock(*args,**kwargs)¶

A mock intended to be used as aproperty, or otherdescriptor, on a class.PropertyMock provides__get__() and__set__() methodsso you can specify a return value when it is fetched.

Fetching aPropertyMock instance from an object calls the mock, withno args. Setting it calls the mock with the value being set.

>>>classFoo:...@property...deffoo(self):...return'something'...@foo.setter...deffoo(self,value):...pass...>>>withpatch('__main__.Foo.foo',new_callable=PropertyMock)asmock_foo:...mock_foo.return_value='mockity-mock'...this_foo=Foo()...print(this_foo.foo)...this_foo.foo=6...mockity-mock>>>mock_foo.mock_calls[call(), call(6)]

Because of the way mock attributes are stored you can’t directly attach aPropertyMock to a mock object. Instead you can attach it to the mock typeobject:

>>>m=MagicMock()>>>p=PropertyMock(return_value=3)>>>type(m).foo=p>>>m.foo3>>>p.assert_called_once_with()

>>>m=MagicMock()>>>no_attribute=PropertyMock(side_effect=AttributeError)>>>type(m).my_property=no_attribute>>>m.my_property<MagicMock name='mock.my_property' id='140165240345424'>

classunittest.mock.AsyncMock(spec=None,side_effect=None,return_value=DEFAULT,wraps=None,name=None,spec_set=None,unsafe=False,**kwargs)¶

An asynchronous version ofMagicMock. TheAsyncMock object willbehave so the object is recognized as an async function, and the result of acall is an awaitable.

>>>mock=AsyncMock()>>>inspect.iscoroutinefunction(mock)True>>>inspect.isawaitable(mock())True

The result ofmock() is an async function which will have the outcomeofside_effect orreturn_value after it has been awaited:

• ifside_effect is a function, the async function will return theresult of that function,

• ifside_effect is an exception, the async function will raise theexception,

• ifside_effect is an iterable, the async function will return thenext value of the iterable, however, if the sequence of result isexhausted,StopAsyncIteration is raised immediately,

• ifside_effect is not defined, the async function will return thevalue defined byreturn_value, hence, by default, the async functionreturns a newAsyncMock object.

Setting thespec of aMock orMagicMock to an async functionwill result in a coroutine object being returned after calling.

>>>asyncdefasync_func():pass...>>>mock=MagicMock(async_func)>>>mock<MagicMock spec='function' id='...'>>>>mock()<coroutine object AsyncMockMixin._mock_call at ...>

Setting thespec of aMock,MagicMock, orAsyncMockto a class with asynchronous and synchronous functions will automaticallydetect the synchronous functions and set them asMagicMock (if theparent mock isAsyncMock orMagicMock) orMock (ifthe parent mock isMock). All asynchronous functions will beAsyncMock.

>>>classExampleClass:...defsync_foo():...pass...asyncdefasync_foo():...pass...>>>a_mock=AsyncMock(ExampleClass)>>>a_mock.sync_foo<MagicMock name='mock.sync_foo' id='...'>>>>a_mock.async_foo<AsyncMock name='mock.async_foo' id='...'>>>>mock=Mock(ExampleClass)>>>mock.sync_foo<Mock name='mock.sync_foo' id='...'>>>>mock.async_foo<AsyncMock name='mock.async_foo' id='...'>

Added in version 3.8.

assert_awaited()¶

Assert that the mock was awaited at least once. Note that this is separatefrom the object having been called, theawait keyword must be used:

>>>mock=AsyncMock()>>>asyncdefmain(coroutine_mock):...awaitcoroutine_mock...>>>coroutine_mock=mock()>>>mock.calledTrue>>>mock.assert_awaited()Traceback (most recent call last):...AssertionError:Expected mock to have been awaited.>>>asyncio.run(main(coroutine_mock))>>>mock.assert_awaited()

assert_awaited_once()¶

Assert that the mock was awaited exactly once.

>>>mock=AsyncMock()>>>asyncdefmain():...awaitmock()...>>>asyncio.run(main())>>>mock.assert_awaited_once()>>>asyncio.run(main())>>>mock.assert_awaited_once()Traceback (most recent call last):...AssertionError:Expected mock to have been awaited once. Awaited 2 times.

assert_awaited_with(*args,**kwargs)¶

Assert that the last await was with the specified arguments.

>>>mock=AsyncMock()>>>asyncdefmain(*args,**kwargs):...awaitmock(*args,**kwargs)...>>>asyncio.run(main('foo',bar='bar'))>>>mock.assert_awaited_with('foo',bar='bar')>>>mock.assert_awaited_with('other')Traceback (most recent call last):...AssertionError:expected await not found.Expected: mock('other')Actual: mock('foo', bar='bar')

assert_awaited_once_with(*args,**kwargs)¶

Assert that the mock was awaited exactly once and with the specifiedarguments.

>>>mock=AsyncMock()>>>asyncdefmain(*args,**kwargs):...awaitmock(*args,**kwargs)...>>>asyncio.run(main('foo',bar='bar'))>>>mock.assert_awaited_once_with('foo',bar='bar')>>>asyncio.run(main('foo',bar='bar'))>>>mock.assert_awaited_once_with('foo',bar='bar')Traceback (most recent call last):...AssertionError:Expected mock to have been awaited once. Awaited 2 times.

assert_any_await(*args,**kwargs)¶

Assert the mock has ever been awaited with the specified arguments.

>>>mock=AsyncMock()>>>asyncdefmain(*args,**kwargs):...awaitmock(*args,**kwargs)...>>>asyncio.run(main('foo',bar='bar'))>>>asyncio.run(main('hello'))>>>mock.assert_any_await('foo',bar='bar')>>>mock.assert_any_await('other')Traceback (most recent call last):...AssertionError:mock('other') await not found

assert_has_awaits(calls,any_order=False)¶

Assert the mock has been awaited with the specified calls.Theawait_args_list list is checked for the awaits.

Ifany_order is false then the awaits must besequential. There can be extra calls before or after thespecified awaits.

Ifany_order is true then the awaits can be in any order, butthey must all appear inawait_args_list.

>>>mock=AsyncMock()>>>asyncdefmain(*args,**kwargs):...awaitmock(*args,**kwargs)...>>>calls=[call("foo"),call("bar")]>>>mock.assert_has_awaits(calls)Traceback (most recent call last):...AssertionError:Awaits not found.Expected: [call('foo'), call('bar')]Actual: []>>>asyncio.run(main('foo'))>>>asyncio.run(main('bar'))>>>mock.assert_has_awaits(calls)

assert_not_awaited()¶

Assert that the mock was never awaited.

>>>mock=AsyncMock()>>>mock.assert_not_awaited()

reset_mock(*args,**kwargs)¶

SeeMock.reset_mock(). Also setsawait_count to 0,await_args to None, and clears theawait_args_list.

await_count¶

An integer keeping track of how many times the mock object has been awaited.

>>>mock=AsyncMock()>>>asyncdefmain():...awaitmock()...>>>asyncio.run(main())>>>mock.await_count1>>>asyncio.run(main())>>>mock.await_count2

await_args¶

This is eitherNone (if the mock hasn’t been awaited), or the arguments thatthe mock was last awaited with. Functions the same asMock.call_args.

>>>mock=AsyncMock()>>>asyncdefmain(*args):...awaitmock(*args)...>>>mock.await_args>>>asyncio.run(main('foo'))>>>mock.await_argscall('foo')>>>asyncio.run(main('bar'))>>>mock.await_argscall('bar')

await_args_list¶

This is a list of all the awaits made to the mock object in sequence (so thelength of the list is the number of times it has been awaited). Before anyawaits have been made it is an empty list.

>>>mock=AsyncMock()>>>asyncdefmain(*args):...awaitmock(*args)...>>>mock.await_args_list[]>>>asyncio.run(main('foo'))>>>mock.await_args_list[call('foo')]>>>asyncio.run(main('bar'))>>>mock.await_args_list[call('foo'), call('bar')]

classunittest.mock.ThreadingMock(spec=None,side_effect=None,return_value=DEFAULT,wraps=None,name=None,spec_set=None,unsafe=False,*,timeout=UNSET,**kwargs)¶

A version ofMagicMock for multithreading tests. TheThreadingMock object provides extra methods to wait for a call tobe invoked, rather than assert on it immediately.

The default timeout is specified by thetimeout argument, or if unset by theThreadingMock.DEFAULT_TIMEOUT attribute, which defaults to blocking (None).

You can configure the global default timeout by settingThreadingMock.DEFAULT_TIMEOUT.

wait_until_called(*,timeout=UNSET)¶

Waits until the mock is called.

If a timeout was passed at the creation of the mock or if a timeoutargument is passed to this function, the function raises anAssertionError if the call is not performed in time.

>>>mock=ThreadingMock()>>>thread=threading.Thread(target=mock)>>>thread.start()>>>mock.wait_until_called(timeout=1)>>>thread.join()

wait_until_any_call_with(*args,**kwargs)¶

Waits until the mock is called with the specified arguments.

If a timeout was passed at the creation of the mockthe function raises anAssertionError if the call is not performed in time.

>>>mock=ThreadingMock()>>>thread=threading.Thread(target=mock,args=("arg1","arg2",),kwargs={"arg":"thing"})>>>thread.start()>>>mock.wait_until_any_call_with("arg1","arg2",arg="thing")>>>thread.join()

DEFAULT_TIMEOUT¶

Global default timeout in seconds to create instances ofThreadingMock.

Added in version 3.13.

>>>m=MagicMock(side_effect=IndexError)>>>m(1,2,3)Traceback (most recent call last):...IndexError>>>m.mock_calls[call(1, 2, 3)]>>>m.side_effect=KeyError('Bang!')>>>m('two','three','four')Traceback (most recent call last):...KeyError:'Bang!'>>>m.mock_calls[call(1, 2, 3), call('two', 'three', 'four')]

>>>defside_effect(value):...returnvalue+1...>>>m=MagicMock(side_effect=side_effect)>>>m(1)2>>>m(2)3>>>m.mock_calls[call(1), call(2)]

>>>m=MagicMock()>>>defside_effect(*args,**kwargs):...returnm.return_value...>>>m.side_effect=side_effect>>>m.return_value=3>>>m()3>>>defside_effect(*args,**kwargs):...returnDEFAULT...>>>m.side_effect=side_effect>>>m()3

>>>m=MagicMock(return_value=6)>>>defside_effect(*args,**kwargs):...return3...>>>m.side_effect=side_effect>>>m()3>>>m.side_effect=None>>>m()6

>>>m=MagicMock(side_effect=[1,2,3])>>>m()1>>>m()2>>>m()3>>>m()Traceback (most recent call last):...StopIteration

>>>iterable=(33,ValueError,66)>>>m=MagicMock(side_effect=iterable)>>>m()33>>>m()Traceback (most recent call last):...ValueError>>>m()66

>>>mock=MagicMock()>>>hasattr(mock,'m')True>>>delmock.m>>>hasattr(mock,'m')False>>>delmock.f>>>mock.fTraceback (most recent call last):...AttributeError:f

>>>mock=MagicMock()>>>mock.configure_mock(name='my_name')>>>mock.name'my_name'

>>>mock=MagicMock()>>>mock.name="foo"

>>>parent=MagicMock()>>>child1=MagicMock(return_value=None)>>>child2=MagicMock(return_value=None)>>>parent.child1=child1>>>parent.child2=child2>>>child1(1)>>>child2(2)>>>parent.mock_calls[call.child1(1), call.child2(2)]

>>>mock=MagicMock()>>>not_a_child=MagicMock(name='not-a-child')>>>mock.attribute=not_a_child>>>mock.attribute()<MagicMock name='not-a-child()' id='...'>>>>mock.mock_calls[]

>>>thing1=object()>>>thing2=object()>>>parent=MagicMock()>>>withpatch('__main__.thing1',return_value=None)aschild1:...withpatch('__main__.thing2',return_value=None)aschild2:...parent.attach_mock(child1,'child1')...parent.attach_mock(child2,'child2')...child1('one')...child2('two')...>>>parent.mock_calls[call.child1('one'), call.child2('two')]

The patchers¶

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

>>>@patch('__main__.SomeClass')...deffunction(normal_argument,mock_class):...print(mock_classisSomeClass)...>>>function(None)True

>>>classClass:...defmethod(self):...pass...>>>withpatch('__main__.Class')asMockClass:...instance=MockClass.return_value...instance.method.return_value='foo'...assertClass()isinstance...assertClass().method()=='foo'...

>>>Original=Class>>>patcher=patch('__main__.Class',spec=True)>>>MockClass=patcher.start()>>>instance=MockClass()>>>assertisinstance(instance,Original)>>>patcher.stop()

>>>thing=object()>>>withpatch('__main__.thing',new_callable=NonCallableMock)asmock_thing:...assertthingismock_thing...thing()...Traceback (most recent call last):...TypeError:'NonCallableMock' object is not callable

>>>fromioimportStringIO>>>deffoo():...print('Something')...>>>@patch('sys.stdout',new_callable=StringIO)...deftest(mock_stdout):...foo()...assertmock_stdout.getvalue()=='Something\n'...>>>test()

>>>patcher=patch('__main__.thing',first='one',second='two')>>>mock_thing=patcher.start()>>>mock_thing.first'one'>>>mock_thing.second'two'

>>>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('sys.non_existing_attribute',42)...deftest():...assertsys.non_existing_attribute==42...>>>test()Traceback (most recent call last):...AttributeError:<module 'sys' (built-in)> does not have the attribute 'non_existing_attribute'

>>>@patch('sys.non_existing_attribute',42,create=True)...deftest(mock_stdout):...assertsys.non_existing_attribute==42...>>>test()

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

>>>foo={}>>>@patch.dict(foo,{'newkey':'newvalue'})...deftest():...assertfoo=={'newkey':'newvalue'}...>>>test()>>>assertfoo=={}

>>>importos>>>importunittest>>>fromunittest.mockimportpatch>>>@patch.dict('os.environ',{'newkey':'newvalue'})...classTestSample(unittest.TestCase):...deftest_sample(self):...self.assertEqual(os.environ['newkey'],'newvalue')

>>>foo={}>>>withpatch.dict(foo,{'newkey':'newvalue'})aspatched_foo:...assertfoo=={'newkey':'newvalue'}...assertpatched_foo=={'newkey':'newvalue'}...# You can add, update or delete keys of foo (or patched_foo, it's the same dict)...patched_foo['spam']='eggs'...>>>assertfoo=={}>>>assertpatched_foo=={}

>>>importos>>>withpatch.dict('os.environ',{'newkey':'newvalue'}):...print(os.environ['newkey'])...newvalue>>>assert'newkey'notinos.environ

>>>mymodule=MagicMock()>>>mymodule.function.return_value='fish'>>>withpatch.dict('sys.modules',mymodule=mymodule):...importmymodule...mymodule.function('some','args')...'fish'

>>>classContainer:...def__init__(self):...self.values={}...def__getitem__(self,name):...returnself.values[name]...def__setitem__(self,name,value):...self.values[name]=value...def__delitem__(self,name):...delself.values[name]...def__iter__(self):...returniter(self.values)...>>>thing=Container()>>>thing['one']=1>>>withpatch.dict(thing,one=2,two=3):...assertthing['one']==2...assertthing['two']==3...>>>assertthing['one']==1>>>assertlist(thing)==['one']

>>>thing=object()>>>other=object()>>>@patch.multiple('__main__',thing=DEFAULT,other=DEFAULT)...deftest_function(thing,other):...assertisinstance(thing,MagicMock)...assertisinstance(other,MagicMock)...>>>test_function()

>>>@patch('sys.exit')...@patch.multiple('__main__',thing=DEFAULT,other=DEFAULT)...deftest_function(mock_exit,other,thing):...assert'other'inrepr(other)...assert'thing'inrepr(thing)...assert'exit'inrepr(mock_exit)...>>>test_function()

>>>withpatch.multiple('__main__',thing=DEFAULT,other=DEFAULT)asvalues:...assert'other'inrepr(values['other'])...assert'thing'inrepr(values['thing'])...assertvalues['thing']isthing...assertvalues['other']isother...

>>>patcher=patch('package.module.ClassName')>>>frompackageimportmodule>>>original=module.ClassName>>>new_mock=patcher.start()>>>assertmodule.ClassNameisnotoriginal>>>assertmodule.ClassNameisnew_mock>>>patcher.stop()>>>assertmodule.ClassNameisoriginal>>>assertmodule.ClassNameisnotnew_mock

>>>classMyTest(unittest.TestCase):...defsetUp(self):...self.patcher1=patch('package.module.Class1')...self.patcher2=patch('package.module.Class2')...self.MockClass1=self.patcher1.start()...self.MockClass2=self.patcher2.start()......deftearDown(self):...self.patcher1.stop()...self.patcher2.stop()......deftest_something(self):...assertpackage.module.Class1isself.MockClass1...assertpackage.module.Class2isself.MockClass2...>>>MyTest('test_something').run()

>>>classMyTest(unittest.TestCase):...defsetUp(self):...patcher=patch('package.module.Class')...self.MockClass=patcher.start()...self.addCleanup(patcher.stop)......deftest_something(self):...assertpackage.module.Classisself.MockClass...

>>>@patch('__main__.ord')...deftest(mock_ord):...mock_ord.return_value=101...print(ord('c'))...>>>test()101

>>>patch.TEST_PREFIX='foo'>>>value=3>>>>>>@patch('__main__.value','not three')...classThing:...deffoo_one(self):...print(value)...deffoo_two(self):...print(value)...>>>>>>Thing().foo_one()not three>>>Thing().foo_two()not three>>>value3

>>>@patch.object(SomeClass,'class_method')...@patch.object(SomeClass,'static_method')...deftest(mock1,mock2):...assertSomeClass.static_methodismock1...assertSomeClass.class_methodismock2...SomeClass.static_method('foo')...SomeClass.class_method('bar')...returnmock1,mock2...>>>mock1,mock2=test()>>>mock1.assert_called_once_with('foo')>>>mock2.assert_called_once_with('bar')

a.py->DefinesSomeClassb.py->fromaimportSomeClass->some_functioninstantiatesSomeClass

@patch('b.SomeClass')

@patch('a.SomeClass')

MagicMock and magic method support¶

>>>def__str__(self):...return'fooble'...>>>mock=Mock()>>>mock.__str__=__str__>>>str(mock)'fooble'

>>>mock=Mock()>>>mock.__str__=Mock()>>>mock.__str__.return_value='fooble'>>>str(mock)'fooble'

>>>mock=Mock()>>>mock.__iter__=Mock(return_value=iter([]))>>>list(mock)[]

>>>mock=Mock()>>>mock.__enter__=Mock(return_value='foo')>>>mock.__exit__=Mock(return_value=False)>>>withmockasm:...assertm=='foo'...>>>mock.__enter__.assert_called_with()>>>mock.__exit__.assert_called_with(None,None,None)

>>>mock=MagicMock()>>>mock[3]='fish'>>>mock.__setitem__.assert_called_with(3,'fish')>>>mock.__getitem__.return_value='result'>>>mock[2]'result'

>>>mock=MagicMock()>>>int(mock)1>>>len(mock)0>>>list(mock)[]>>>object()inmockFalse

>>>MagicMock()==3False>>>MagicMock()!=3True>>>mock=MagicMock()>>>mock.__eq__.return_value=True>>>mock==3True

>>>mock=MagicMock()>>>mock.__iter__.return_value=['a','b','c']>>>list(mock)['a', 'b', 'c']>>>list(mock)['a', 'b', 'c']

>>>mock.__iter__.return_value=iter(['a','b','c'])>>>list(mock)['a', 'b', 'c']>>>list(mock)[]

Helpers¶

>>>real=ProductionClass()>>>real.method=Mock(name="method")>>>real.method.return_value=sentinel.some_object>>>result=real.method()>>>assertresultissentinel.some_object>>>resultsentinel.some_object