快速導引¶

Mock 和MagicMock 物件在你存取它們時建立所有屬性和 method（方法），並儲存它們如何被使用的詳細訊息。你可以配置它們，以指定回傳值或限制可用的屬性，然後對它們的使用方式做出判定：

>>>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 允許你執行 side effects，包含在 mock 被呼叫時引發例外：

>>>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 有許多其他方法可以讓你配置與控制它的行為。例如，spec 引數可以配置 mock ，讓其從另一個物件取得規格。嘗試讀取 mock 中不存在於規格中的屬性或方法將會失敗，並出現AttributeError。

patch() 裝飾器／情境管理器可以在測試中簡單的 mock 模組中的類別或物件。被指定的物件在測試期間會被替換為 mock（或其他物件），並在測試結束時恢復：

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

裝飾器patch() 也可以在 with 陳述式中被用來作為情境管理器：

>>>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)

也有patch.dict()，用於在測試範圍中設定 dictionary（字典）內的值，並在測試結束時將其恢復為原始狀態：

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

Mock 支援對 Python 的魔術方法的 mocking。最簡單使用魔術方法的方式是使用MagicMock 類別。它允許你執行以下操作：

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

Mock 允許你將函式（或其他 Mock 實例）分配給魔術方法，並且它們將被適當地呼叫。MagicMock 類別是一個 Mock 的變體，它為你預先建好了所有魔術方法（好吧，所有有用的方法）。

以下是在一般 Mock 類別中使用魔術方法的範例：

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

為了確保測試中的 mock 物件與它們要替換的物件具有相同的 api，你可以使用自動規格。自動規格（auto-speccing）可以通過 patch 的autospec 引數或create_autospec() 函式來完成。自動規格建立的 mock 物件與它們要替換的物件具有相同的屬性和方法，並且任何函式和方法（包括建構函式）都具有與真實物件相同的呼叫簽名（call signature）。

這可以確保如果使用方法錯誤，你的 mock 會跟實際程式碼以相同的方式失敗：

>>>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() 也可以用在類別上，它複製了__init__ 方法的簽名，它也可以用在可呼叫物件上，其複製了__call__ 方法的簽名。

Mock 類別¶

Mock 是一個彈性的的 mock 物件，旨在代替程式碼中 stubs 和 test doubles （測試替身）的使用。Mock 是可呼叫的，並在你存取它們時將屬性建立為新的 mock[1]。存取相同的屬性將永遠回傳相同的 mock。Mock 記錄了你如何使用它們，允許你判定你的程式碼對 mock 的行為。

MagicMock 是Mock 的子類別，其中所有魔術方法均已預先建立並可供使用。也有不可呼叫的變體，在你 mock 無法呼叫的物件時很有用：NonCallableMock 和NonCallableMagicMock

patch() 裝飾器可以輕鬆地用Mock 物件臨時替換特定模組中的類別。預設情況下，patch() 會為你建立一個MagicMock。你可以使用patch() 的new_callable 引數指定Mock 的替代類別。

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

建立一個新的Mock 物件。Mock 接受數個可選的引數來指定 Mock 物件的行為：

• spec：這可以是字串的 list（串列），也可以是充當 mock 物件規格的現有物件（類別或實例）。如果傳入一個物件，則通過對該物件呼叫 dir 來形成字串的串列（不包括不支援的魔術屬性和方法）。存取不在此串列中的任何屬性都會引發AttributeError。

  如果spec 是一個物件（而不是一個字串的串列），那麼__class__ 會回傳 spec 物件的類別。這允許 mocks 通過isinstance() 測試。

• spec_set：spec 的一個更嚴格的變體。如果使用spec_set，在 mock 上嘗試set 或取得不在傳遞給spec_set 的物件上的屬性將會引發AttributeError。

• side_effect：每當呼叫 Mock 時要呼叫的函式，參見side_effect 屬性，用於引發例外或動態變更回傳值。該函式使用與 mock 相同的引數呼叫，且除非它回傳DEFAULT，否則此函式的回傳值將用作回傳值。

  side_effect 也可以是一個例外的類別或實例。在這種情況下，當呼叫 mock 時，該例外將被引發。

  如果side_effect 是一個可疊代物件，那麼對 mock 的每次呼叫將回傳可疊代物件中的下一個值。

  side_effect 可以通過將其設置為None 來清除。

• return_value：當呼叫 mock 時回傳的值。預設情況下，這是一個新的 Mock（在首次存取時建立）。參見return_value 屬性。

• unsafe：預設情況下，存取任何以assert、assret、asert、aseert 或assrt 開頭的屬性將引發AttributeError。如果傳遞unsafe=True，將會允許存取這些屬性。

  在 3.5 版被加入.

• wraps：被 mock 物件包裝的項目。如果wraps 不是None，那麼呼叫 Mock 將通過被包裝的物件（回傳真實結果）。存取 mock 的屬性將會回傳一個 Mock 物件，該物件包裝了被包裝物件的對應屬性（因此嘗試存取不存在的屬性將引發AttributeError）。

  如果 mock 已經明確設定了return_value，那麼呼叫並不會被傳遞到被包裝的物件，而是回傳已設定好的return_value。

• name：如果 mock 有一個名稱，那麼它會被用於 mock 的 repr。這對於除錯很有用。此名稱將被傳播到子 mocks。

Mocks 還可以使用任意的關鍵字引數進行呼叫。這些關鍵字引數將在建立 mock 之後用於設定 mock 的屬性。欲知更多，請參見configure_mock() 方法。

assert_called()¶

確認 mock 至少被呼叫一次。

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

在 3.6 版被加入.

assert_called_once()¶

確認 mock 只被呼叫一次。

>>>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()].

在 3.6 版被加入.

assert_called_with(*args,**kwargs)¶

這個方法是一個便利的方式，用來斷言最後一次呼叫是以特定方式進行的：

>>>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)¶

確認 mock 只被呼叫一次，且該次呼叫使用了指定的引數。

>>>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)¶

斷言 mock 已經被使用指定的引數呼叫。

這個斷言在 mock 曾經被呼叫過時通過，不同於assert_called_with() 和assert_called_once_with()，他們針對的是最近的一次的呼叫，而且對於assert_called_once_with()，最近一次的呼叫還必須也是唯一一次的呼叫。

>>>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)¶

斷言 mock 已經使用指定的呼叫方式來呼叫。此斷言會檢查mock_calls 串列中的呼叫。

如果any_order 為 false，那麼這些呼叫必須按照順序。在指定的呼叫之前或之後可以有額外的呼叫。

如果any_order 為 true，那麼這些呼叫可以以任何順序出現，但它們必須全部出現在mock_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()¶

斷言 mock 從未被呼叫。

>>>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()].

在 3.5 版被加入.

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

reset_mock 方法重置 mock 物件上的所有呼叫屬性：

>>>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.

在 3.6 版的變更:reset_mock 函式新增了兩個僅限關鍵字引數 (keyword-only arguments)。

mock_add_spec(spec,spec_set=False)¶

向 mock 增加一個規格 (spec)。spec 可以是一個物件或一個字串串列 (list of strings)。只有在spec 上的屬性才能作為 mock 的屬性被取得。

如果spec_set 為 true，那麼只能設定在規格中的屬性。

attach_mock(mock,attribute)¶

將一個 mock 作為這個 Mock 的屬性附加，取代它的名稱和上代 (parent)。對附加的 mock 的呼叫將被記錄在這個 Mock 的method_calls 和mock_calls 屬性中。

configure_mock(**kwargs)¶

透過關鍵字引數在 mock 上設定屬性。

可以在使用 method（方法）呼叫時，使用標準點記法 (dot notation) 並將字典拆開，為 child mock 設定屬性、回傳值和 side effects：

>>>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

同樣的事情可以在 mock 的建構函式呼叫中實現：

>>>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() 的存在是為了在 mock 被建立後更容易進行組態設定。

__dir__()¶

Mock 物件限制了dir(some_mock) 僅顯示有用的結果。對於具有spec 的 mock，這包含所有被允許的 mock 屬性。

請參閱FILTER_DIR 以了解這種過濾行為的作用，以及如何關閉它。

_get_child_mock(**kw)¶

建立為了得到屬性和回傳值的 child mock。預設情況下，child mock 將與其上代是相同的型別。Mock 的子類別可能會想要置換此行為，以自定義 child mock 的建立方式。

對於不可呼叫的 mock，將使用可呼叫的變體，而不是任何的自定義子類別。

called¶

一個 boolean（布林），表述 mock 物件是否已經被呼叫：

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

call_count¶

一個整數，告訴你 mock 物件被呼叫的次數：

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

return_value¶

設定此值以配置呼叫 mock 時回傳的值：

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

預設的回傳值是一個 mock 物件，你也可以按照正常的方式配置它：

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

return_value 也可以在建構函式中設定：

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

side_effect¶

這可以是一個在呼叫 mock 時要呼叫的函式、一個可疊代物件，或者要引發的例外（類別或實例）。

如果你傳遞一個函式，它將被呼叫，其引數與 mock 相同，且除非該函式回傳DEFAULT 單例 (singleton)，否則對 mock 的呼叫將回傳函式回傳的任何值。如果函式回傳DEFAULT，那麼 mock 將回傳其正常的回傳值（從return_value 得到）。

如果你傳遞一個可疊代物件，它將被用於檢索一個疊代器，該疊代器必須在每次呼叫時產出 (yield) 一個值。這個值可以是要引發的例外實例，或者是對 mock 呼叫時要回傳的值（處理DEFAULT 的方式與函式的狀況相同）。

以下是一個引發例外的 mock 的範例（用於測試 API 的例外處理）：

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

使用side_effect 回傳一連串值的範例：

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

使用可被呼叫物件的範例：

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

side_effect 可以在建構函式中設定。以下是一個範例，它將 mock 被呼叫時給的值加一並回傳：

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

將side_effect 設定為None 可以清除它：

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

call_args¶

這會是None（如果 mock 尚未被呼叫），或是 mock 上次被呼叫時使用的引數。這將以元組的形式呈現：第一個成員 (member)，其可以通過args 屬性存取，是 mock 被呼叫時傳遞的所有有序引數（或一個空元組）。第二個成員，其可以通過kwargs 屬性存取，是所有關鍵字引數（或一個空字典）。

>>>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，以及串列call_args_list、method_calls 和mock_calls 的成員都是call 物件。這些都是元組，因此可以解包以取得各個引數並進行更複雜的斷言。參見calls as tuples。

在 3.8 版的變更:新增args 與kwargs 特性。

call_args_list¶

這是按順序列出所有呼叫 mock 物件的串列（因此串列的長度表示它被呼叫的次數）。在任何呼叫發生之前，它會是一個空的串列。call 物件可用於方便地建構呼叫的串列，以便與call_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

call_args_list 的成員都是call 物件。這些物件可以被拆包為元組，以取得各個引數。參見calls as tuples。

method_calls¶

除了追蹤對自身的呼叫之外，mock 還會追蹤對方法和屬性的呼叫，以及它們（這些方法和屬性）的方法和屬性：

>>>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()]

method_calls 的成員都是call 物件。這些物件可以拆包為元組，以取得各個引數。參見calls as tuples。

mock_calls¶

mock_calls 記錄了所有 對 mock 物件的呼叫，包含其方法、魔術方法以及回傳值 mock。

>>>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

method_calls 的成員都是call 物件。這些物件可以拆包為元組，以取得各個引數。參見calls as tuples。

備註

mock_calls 記錄的方式意味著在進行巢狀呼叫時，上代 (ancestor) 呼叫的參數不會被記錄，因此在比較時它們將始終相等：

>>>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__¶

通常，物件的__class__ 屬性會回傳它的型別。但對於擁有spec 的 mock 物件，__class__ 會回傳 spec 的類別。這允許 mock 物件通過對它們所替代或偽裝的物件進行的isinstance() 測試：

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

__class__ 可以被指定，這允許 mock 通過isinstance() 檢查，而不需要強制使用 spec：

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

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

Mock 的一個不可呼叫版本。建構函式參數的意義與Mock 相同，其例外為return_value 和side_effect 在不可呼叫的 mock 上無意義。

使用類別或實例作為spec 或spec_set 的 mock 物件能夠通過isinstance() 測試：

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

Mock 類別支援 mock 魔術方法。細節請參考魔術方法。

Mock類別和patch() 裝飾器於組態時接受任意的關鍵字引數。對於patch() 裝飾器，這些關鍵字會傳遞給正在建立 mock 的建構函式。這些關鍵字引數用於配置 mock 的屬性：

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

Child mock 的回傳值和 side effect 可以使用使用點記法進行設置。由於你無法直接在呼叫中使用帶有點 (.) 的名稱，因此你必須建立一個字典並使用** 解包：

>>>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

在匹配對 mock 的呼叫時，使用spec（或spec_set）建立的可呼叫 mock 將會內省 (introspect) 規格物件的簽名 (signature)。因此，它可以匹配實際呼叫的引數，無論它們是按位置傳遞還是按名稱傳遞：

>>>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)

這適用於assert_called_with()、assert_called_once_with()、assert_has_calls() 和assert_any_call()。在使用Autospeccing（自動規格） 時，它還適用於 mock 物件的方法呼叫。

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

一個理應在類別上當成property 或其他descriptor 的 mock。PropertyMock 提供了__get__() 和__set__() 方法，因此你可以在它被提取時指定回傳值。

從物件中提取PropertyMock 實例會不帶任何引數呼叫 mock。設定它則會用設定的值來呼叫 mock：

>>>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)]

由於 mock 屬性的儲存方式，你無法直接將PropertyMock 附加到 mock 物件。但是你可以將其附加到 mock 型別的物件：

>>>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)¶

MagicMock 的非同步版本。AsyncMock 物件的表現將被視為非同步函式，並且呼叫的結果是一個可等待物件。

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

mock() 的結果是一個非同步函式，在它被等待後將具有side_effect 或return_value 的結果：

• 如果side_effect 是一個函式，非同步函式將回傳該函式的結果，

• 如果side_effect 是一個例外，則非同步函式將引發該例外，

• 如果side_effect 是一個可疊代物件，非同步函式將回傳可疊代物件的下一個值，但如果結果序列耗盡，將立即引發StopAsyncIteration，

• 如果side_effect 沒有被定義，非同步函式將回傳由return_value 定義的值，因此在預設情況下，非同步函式回傳一個新的AsyncMock 物件。

將Mock 或MagicMock 的spec 設定為非同步函式將導致在呼叫後回傳一個協程物件。

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

將Mock、MagicMock 或AsyncMock 的spec 設定為具有同步和非同步函式的類別，會自動檢測同步函式並將其設定為MagicMock（如果上代 mock 為AsyncMock 或MagicMock）或Mock（如果上代 mock 為Mock）。所有非同步函式將被設定為AsyncMock。

>>>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='...'>

在 3.8 版被加入.

assert_awaited()¶

斷言 mock 至少被等待過一次。請注意這與物件是否被呼叫是分開的，await 關鍵字必須被使用：

>>>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()¶

斷言 mock 正好被等待了一次。

>>>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)¶

斷言最後一次等待使用了指定的引數。

>>>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)¶

斷言 mock 只被等待了一次並使用了指定的引數。

>>>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)¶

斷言 mock 曾經被使用指定的引數等待過。

>>>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)¶

斷言 mock 已被使用指定的呼叫進行等待。await_args_list 串列將被檢查以確認等待的內容。

如果any_order 為 false，則等待必須按照順序。指定的等待之前或之後可以有額外的呼叫。

如果any_order 為 true，則等待可以以任何順序出現，但它們必須全部出現在await_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()¶

斷言 mock 從未被等待。

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

reset_mock(*args,**kwargs)¶

參見Mock.reset_mock()。同時將await_count 設定為 0，await_args 設定為 None，並清除await_args_list。

await_count¶

一個整數，用來記錄 mock 物件已被等待的次數。

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

await_args¶

這可能是None（如果 mock 尚未被等待），或者是上次等待 mock 時使用的引數。與Mock.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¶

這是一個按照順序記錄 mock 物件所有等待的串列（因此串列的長度表示該物件已被等待的次數）。在進行任何等待之前，此串列為空。

>>>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)¶

等待直到 mock 被呼叫。

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)¶

等到直到 mock 被以特定引數呼叫。

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.

在 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')]

Patchers¶

patch 裝飾器僅用於在裝飾的函式範圍內對物件進行 patch。它們會自動為你處理 patch 的中止，即使有異常被引發也是如此。所有這些函式也可以在 with 陳述式中使用，或者作為類別裝飾器使用。

>>>@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 以及魔術方法支援¶

>>>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)[]

輔助函式¶

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