unittest.mock --- モックオブジェクトライブラリ

Added in version 3.3.

ソースコード: Lib/unittest/mock.py

---

unittest.mock は Python でテストを行うためのライブラリです。 テスト対象のシステムの一部をモックオブジェクトに置き換え、どのように使われたかをアサートできます。

unittest.mock は中核となる Mock クラスを提供し、テストスイート全体で数多くのスタブを作成する手間を省きます。 操作を実行した後、どのメソッドや属性が使われたか、どの引数で呼び出されたかをアサートできます。 戻り値を指定したり、必要な属性を通常の方法で設定したりすることもできます。

加えて、 mock はテストのスコープ内にあるモジュールやクラスの属性を変更する patch() デコレータを提供します。さらに、ユニークなオブジェクトの作成には sentinel が利用できます。 Mock や MagicMock 、 patch() の利用例は quick guide を参照してください。

Mock は unittest で利用するために設計されており、多くのモックフレームワークで使われる 'record -> replay' パターンの代わりに、 'action -> assertion' パターンに基づいています。

古いバージョンの Python 向けに unittest.mock をバックポートしたものが、PyPI の mock として提供されています。

クイックガイド

Mock および MagicMock オブジェクトはアクセスしたすべての属性とメソッドを作成し、どのように使用されたかについての詳細な情報を格納します。戻り値を指定したり利用できる属性を制限するために Mock および MagicMock を設定でき、どのよう使用されたかについてアサートできます:

>>> from unittest.mock import MagicMock
>>> 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 によって、モック呼び出し時の例外発生などの副作用を実行できます:

>>> from unittest.mock import Mock
>>> mock = Mock(side_effect=KeyError('foo'))
>>> mock()
Traceback (most recent call last):
 ...
KeyError: 'foo'

>>> values = {'a': 1, 'b': 2, 'c': 3}
>>> def side_effect(arg):
...     return values[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)

モックには多くの設定法や挙動の制御法があります。例えば spec 引数によって別のオブジェクトからの仕様を受け取るよう設定できます。 spec にないモックの属性やメソッドにアクセスを試みた場合、 AttributeError で失敗します。

patch() デコレータ / コンテキストマネージャーによってテスト対象のモジュール内のクラスやオブジェクトを簡単にモックできます。指定したオブジェクトはテスト中はモック (または別のオブジェクト) に置換され、テスト終了時に復元されます:

>>> from unittest.mock import patch
>>> @patch('module.ClassName2')
... @patch('module.ClassName1')
... def test(MockClass1, MockClass2):
...     module.ClassName1()
...     module.ClassName2()
...     assert MockClass1 is module.ClassName1
...     assert MockClass2 is module.ClassName2
...     assert MockClass1.called
...     assert MockClass2.called
...
>>> test()

注釈

patch デコレータをネストした場合、モックは適用されるときと同じ順番 (デコレータを適用するときの通常の Python の順番) でデコレートされた関数に渡されます。 つまり下から順に適用されるため、上の例では module.ClassName1 のモックが最初に渡されます。

patch() では探索される名前空間内のオブジェクトにパッチをあてることが重要です。通常は単純ですが、詳しくは どこにパッチするか を参照してください。

patch() デコレータと同様に with 文でコンテキストマネージャーとして使用できます:

>>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method:
...     thing = ProductionClass()
...     thing.method(1, 2, 3)
...
>>> mock_method.assert_called_once_with(1, 2, 3)

また、 patch.dict() を使うと、スコープ内だけで辞書に値を設定し、テスト終了時には元の状態に復元されます:

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

mock は Python の マジックメソッド のモックをサポートしています。 マジックメソッドのもっとも簡単な利用法は 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'

テスト内のモックオブジェクトが置換するオブジェクトと同じ API を持つことを保証するには、 auto-speccing を使うことができます。パッチをあてる autospec 引数、または create_autospec() 関数を通じて auto-speccing は行われます。 auto-speccing は置換するオブジェクトと同じ属性とメソッドを持つモックオブジェクトを作成し、すべての関数および (コンストラクタを含む) メソッドは本物のオブジェクトと同じ呼び出しシグネチャを持ちます。

誤って使用された場合、モックは製品コードと同じように失敗されることが保証されています:

>>> from unittest.mock import create_autospec
>>> def function(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 は、コードにおけるスタブの使用やテストダブルを置き換えるための柔軟なモックオブジェクトです。モックは呼び出し可能で、属性にアクセスした場合それを新たなモックとして作成します [1]。同じ属性にアクセスした場合は常に同じモックを返します。 モックはどのように使われたかを記録するので、コードがモックに行うことについてアサートできます。

MagicMock は Mock のサブクラスで、すべてのマジックメソッドが事前に作成され、利用できます。また、呼び出し不可能なモックを作成する場合には、呼び出し不能な変種の NonCallableMock や NonCallableMagicMock があります。

patch() デコレータによって特定のモジュール内のクラスを Mock オブジェクトで一時的に置換することが簡単にできます。デフォルトでは patch() は MagicMock を作成します。 patch() に渡す new_callable 引数によって、別の Mock クラスを指定できます。

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

新しい Mock オブジェクトを作成します。 Mock はモックオブジェクトの挙動を指定するオプション引数をいくつか取ります:

• spec: モックオブジェクトの仕様として働く文字列のリストもしくは存在するオブジェクト (クラスもしくはインスタンス) を指定します。オブジェクトを渡した場合には、 dir 関数によって文字列のリストが生成されます (サポートされない特殊属性や特殊メソッドは除く) 。このリストにない属性にアクセスした際には AttributeError が発生します。

  spec が (文字列のリストではなく) オブジェクトの場合、 __class__ はスペックオブジェクトのクラスを返します。これによってモックが isinstance() テストに通るようになります。

• spec_set: より厳しい spec です。こちらを利用した場合、 spec_set に渡されたオブジェクトに存在しない属性に対し 設定 や取得をしようとした際に AttributeError が発生します。

• side_effect: モックが呼び出された際に呼び出される関数を指定します。 side_effect 属性を参考にしてください。例外を発生させたり、動的に戻り値を変更する場合に便利です。関数には、モックと同じ引数が渡され、 DEFAULT を返さない限りはこの関数の戻り値が使われます。

  一方で、 side_effect には、例外クラスやインスタンスを指定できます。この場合は、モックが呼び出された際に指定された例外を発生します。

  もし、 side_effect にイテレート可能オブジェクトを指定した場合には、モックの呼び出しごとに順に値を返します。

  side_effect に None を指定した場合には、設定がクリアされます。

• return_value: モックが呼び出された際に返す値です。デフォルトでは (最初にアクセスされた際に生成される) 新しい Mock を返します。 return_value を参照してください。

• unsafe: デフォルトでは、名前が assert、assret、asert、aseert、assrt のいずれかで始まる属性にアクセスすると AttributeError が送出されます。 unsafe=True を渡すと、これらの属性へのアクセスを許可します。

  Added in version 3.5.

• wraps: このモックオブジェクトがラップするものです。 wraps が None でなければ、このモックを呼び出すと、その呼び出しがラップされたオブジェクトに渡され (て実際の結果を返し) ます。モックの属性アクセスは、ラップされたオブジェクトの対応する属性をラップする Mock オブジェクトを返します (なので、存在しない属性にアクセスしようとすると AttributeError を送出します)。

  モックが明示的に return_value を設定されていると、呼び出しはラップされたオブジェクトに渡されず、代わりに return_value が返されます。

• name: モックに名前がある場合、その名前はモックの repr() の結果に使われます。 デバッグに役立つことがあります。 名前は子モックにも伝播します。

モックは、任意のキーワード引数を与えることができます。これらはモックの生成後、属性の設定に使われます。詳細は configure_mock() を参照してください。

assert_called()

モックが少なくとも一度は呼び出されたことをアサートします。

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

Added in version 3.6.

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

このメソッドを使うと、最後の呼び出しが特定の引数で行われたことを簡単にアサートできます。

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

モックが一度も呼ばれなかったことをアサートします。

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

モックオブジェクトのすべての呼び出し属性をリセットします:

>>> mock = Mock(return_value=None)
>>> mock('hello')
>>> mock.called
True
>>> mock.reset_mock()
>>> mock.called
False

同じオブジェクトを再利用して一連のアサートを行いたい場合に役立ちます。

return_value 引数を True にすると、return_value をリセットします。

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

side_effect 引数を True にすると、side_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='...'>

デフォルトでは reset_mock() は return_value、side_effect、および通常の代入で設定した子の属性をクリア しません。

子モックもリセットされます。

バージョン 3.6 で変更: 2つのキーワード専用引数が reset_mock 関数に追加されました。

mock_add_spec(spec, spec_set=False)

モックに仕様を追加します。 spec にはオブジェクトまたは文字列のリストを指定できます。 モックの属性として取得できるのは、spec にある属性だけです。

spec_set が真なら、 spec 以外の属性は設定できません。

attach_mock(mock, attribute)

属性として mock を設定して、その名前と親を入れ替えます。設定されたモックの呼び出しは、 method_calls や mock_calls 属性に記録されます。

configure_mock(**kwargs)

モックの属性をキーワード引数で設定します。

属性に加え、子の戻り値や副作用もドット表記を用いて設定でき、辞書はメソッドの呼び出し時にアンパックされます:

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

コンストラクタの呼び出しでも同様に行うことができます:

>>> 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() は、モック生成後のコンフィギュレーションを容易に行うために存在します。

__dir__()

Mock オブジェクトは、dir(some_mock) の結果を有用なものに絞ります。 spec を指定したモックでは、モックに許可された属性がすべて含まれます。

このフィルタが何をしていて、どのように停止させるかは、 FILTER_DIR を参照してください。

_get_child_mock(**kw)

属性用と戻り値用の子モックを作成します。 デフォルトでは、子モックは親と同じ型になります。 Mock のサブクラスで子モックの作成方法をカスタマイズしたい場合は、このメソッドをオーバーライドできます。

呼び出し不可能なモックに対しては、(カスタムのサブクラスではなく) 呼び出し可能なモックが使われます。

called

このモックが呼び出されたかどうかを表します:

>>> mock = Mock(return_value=None)
>>> mock.called
False
>>> mock()
>>> mock.called
True

call_count

このモックオブジェクトが呼び出された回数を返します:

>>> mock = Mock(return_value=None)
>>> mock.call_count
0
>>> mock()
>>> mock()
>>> mock.call_count
2

return_value

モックが呼び出された際に返す値を設定します:

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

デフォルトの戻り値はモックオブジェクトです。通常の方法で設定することもできます:

>>> 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_value
3
>>> mock()
3

side_effect

このモックが呼ばれた際に呼び出される関数、イテラブル、もしくは発生させる例外 (クラスまたはインスタンス) を設定できます。

関数を渡した場合はモックと同じ引数で呼び出され、 DEFAULT を返さない限りはその関数の戻り値が返されます。関数が DEFAULT を返した場合は ( return_value によって) モックの通常の値を返します。

iterable が渡された場合、その値はイテレータを取り出すために使用されます。 イテレータは毎回の呼び出しにおいて値を yield しなければなりません。 この値は、送出される例外インスタンスか、モックの呼び出しから返される値のいずれかです (DEFAULT の処理は関数の場合と同一です)。

以下はモックが (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)
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> mock.side_effect = side_effect
>>> mock()
3

side_effect は生成時にも設定可能です。呼び出し時の値に 1 を加えて返す例を以下に示します:

>>> side_effect = lambda value: 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、呼び出されていれば最後の呼び出しに渡された引数です。 タプルの形式で、最初の要素はモックに渡された位置引数 (なければ空のタプル)、2 番目の要素はキーワード引数 (なければ空の辞書) です。 最初の要素には args プロパティ、2 番目の要素には kwargs プロパティでもアクセスできます。

>>> mock = Mock(return_value=None)
>>> print(mock.call_args)
None
>>> mock()
>>> mock.call_args
call()
>>> mock.call_args == ()
True
>>> mock(3, 4)
>>> mock.call_args
call(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_args
call(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

モックの呼び出しを順に記録したリストです (よって、このリストの長さはモックが呼び出された回数と等しくなります)。モックを作成してから一度も呼び出しを行なっていない場合は、空のリストが返されます。 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 == expected
True

call_args_list のメンバは call オブジェクトです。タプルとしてアンパックすることで個別に取り出すことができます。 calls as tuples を参照してください。

method_calls

自身の呼び出しと同様に、モックはメソッドや属性、そして それらの メソッドや属性の呼び出しも追跡します:

>>> 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 = 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 == expected
True

mock_calls のメンバは call オブジェクトです。タプルとしてアンパックすることで個別に取り出すことができます。 calls as tuples を参照してください。

注釈

mock_calls の記録方法により、入れ子の呼び出しでは祖先の呼び出しの引数が記録されません。 そのため、祖先の呼び出しの引数が異なっても、比較すると常に等しいと判定されます。

>>> 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 を指定したモックオブジェクトでは、__class__ は代わりに仕様に指定したクラスを返します。 このため、モックオブジェクトは置き換えたり、なりすましたりしているオブジェクトに対する isinstance() の検査に通ります。

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

__class__ は書き換え可能で、 isinstance() を通るために必ず spec を使う必要はありません:

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

class unittest.mock.NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs)

呼び出しができない Mock です。コンストラクタのパラメータは Mock と同様ですが、 return_value や side_effect は意味を持ちません。

spec か spec_set にクラスかインスタンスを渡した mock は isinstance() テストをパスします:

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

Mock クラスは、 特殊メソッドをサポートしています。すべての詳細は magic methods を参照してください。

モッククラスや patch() デコレータは、任意のキーワード引数を設定できます。 patch() デコレータへのキーワード引数は、モックが作られる際のコンストラクタに渡されます。キーワード引数は、モックの属性を設定します:

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

子の戻り値や副作用も、ドットで表記することで同様に設定できます。呼び出し時に直接ドットのついた名前を使用できないので、作成した辞書を ** でアンパックする必要があります:

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

spec (または spec_set) を指定して作成した呼び出し可能なモックは、呼び出しを照合するときに仕様となるオブジェクトのシグネチャを調べます。 そのため、実際の呼び出しの引数が位置引数として渡されたか、名前を指定して渡されたかにかかわらず照合できます。

>>> def f(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() に適用されます。 autospec を使う を使う場合は、モックオブジェクトのメソッド呼び出しにも適用されます。

バージョン 3.4 で変更: spec や autospec を用いて生成されたモックオブジェクトは、シグネチャを考慮するようになりました。

class unittest.mock.PropertyMock(*args, **kwargs)

property もしくは デスクリプタ として使われるためのモックです。 PropertyMock は、 __get__() と __set__() メソッドを提供し、戻り値を指定することができます。

オブジェクトから PropertyMock のインスタンスを取得することは、引数を与えないモックの呼び出しに相当します。設定は、 設定する値を伴った呼び出しになります。:

>>> class Foo:
...     @property
...     def foo(self):
...         return 'something'
...     @foo.setter
...     def foo(self, value):
...         pass
...
>>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_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)]

PropertyMock を直接モックに取り付ける方法は、モックの属性を保存する方法によりうまく動作しません。代わりに、モック型に取り付けてください:

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

注意

PropertyMock が AttributeError を送出すると、デスクリプタがないものと解釈され、親モックの __getattr__() が呼び出されます。

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

詳細は __getattr__() を参照してください。

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

MagicMock の非同期版です。 AsyncMock オブジェクトは非同期関数として認識されるように振る舞い、呼び出した結果は await 可能です。

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

The result of mock() is an async function which will have the outcome of side_effect or return_value after it has been awaited:

• side_effect が関数の場合、この非同期関数はその関数の結果を返します。

• side_effect が例外の場合、この非同期関数はその例外を送出します。

• side_effect がイテラブルの場合、この非同期関数はイテラブルの次の値を返します。 ただし、結果のシーケンスが 尽きた 場合は、ただちに StopAsyncIteration を送出します。

• side_effect を定義していない場合、この非同期関数は return_value に定義した値を返します。 従って、デフォルトでは新しい AsyncMock オブジェクトを返します。

Mock または MagicMock の spec に非同期関数を指定すると、呼び出した結果としてコルーチンオブジェクトを返します。

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

Mock、MagicMock、AsyncMock の spec に、非同期関数と同期関数を持つクラスを指定すると、同期関数を自動的に検出します。 同期関数には、親モックが AsyncMock または MagicMock なら MagicMock、親モックが Mock なら Mock を設定します。 非同期関数はすべて AsyncMock になります。

>>> class ExampleClass:
...     def sync_foo():
...         pass
...     async def async_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()

モックが少なくとも一度 await されたことをアサートします。 オブジェクトが呼び出されたこととは別であり、await キーワードを使う必要があります。

>>> mock = AsyncMock()
>>> async def main(coroutine_mock):
...     await coroutine_mock
...
>>> coroutine_mock = mock()
>>> mock.called
True
>>> 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()

モックがちょうど一度 await されたことをアサートします。

>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> 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)

最後の await が指定した引数で行われたことをアサートします。

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*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)

モックがちょうど一度、指定した引数で await されたことをアサートします。

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*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)

モックが指定した引数で一度でも await されたことをアサートします。

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*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)

モックが指定した呼び出しで await されたことをアサートします。 await は await_args_list リストで確認します。

any_order が偽の場合、await は連続している必要があります。 指定した await の前後には、他の呼び出しがあっても構いません。

any_order が真の場合、await の順序は問いませんが、すべてが await_args_list に含まれる必要があります。

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*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()

モックが一度も await されていないことをアサートします。

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

reset_mock(*args, **kwargs)

Mock.reset_mock() を参照してください。 加えて、await_count を 0、await_args を None に設定し、await_args_list を空にします。

await_count

モックオブジェクトが await された回数を記録する整数です。

>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.await_count
1
>>> asyncio.run(main())
>>> mock.await_count
2

await_args

モックがまだ await されていなければ None、されていれば最後に await されたときの引数です。 Mock.call_args と同じように機能します。

>>> mock = AsyncMock()
>>> async def main(*args):
...     await mock(*args)
...
>>> mock.await_args
>>> asyncio.run(main('foo'))
>>> mock.await_args
call('foo')
>>> asyncio.run(main('bar'))
>>> mock.await_args
call('bar')

await_args_list

モックオブジェクトに対するすべての await を順に記録したリストです (従って、リストの長さは await された回数です)。 一度も await されていなければ空のリストです。

>>> mock = AsyncMock()
>>> async def main(*args):
...     await mock(*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')]

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

マルチスレッドのテスト用の MagicMock です。 ThreadingMock オブジェクトは、呼び出しがあったかを即座にアサートする代わりに、呼び出されるまで待機するメソッドを追加で提供します。

デフォルトのタイムアウトは timeout 引数で指定します。 指定しない場合は ThreadingMock.DEFAULT_TIMEOUT 属性を使い、そのデフォルト値は無期限にブロックする None です。

ThreadingMock.DEFAULT_TIMEOUT を設定すると、全体のデフォルトのタイムアウトを変更できます。

wait_until_called(*, timeout=UNSET)

モックが呼び出されるまで待機します。

モックの作成時またはこの関数の timeout 引数にタイムアウトを指定した場合、 制限時間内に呼び出されなければ AssertionError を送出します。

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

wait_until_any_call_with(*args, **kwargs)

モックが指定した引数で呼び出されるまで待機します。

モックの作成時にタイムアウトを指定した場合、制限時間内に呼び出されなければ AssertionError を送出します。

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

ThreadingMock のインスタンスを作成するときに使う、秒単位のグローバルなデフォルトのタイムアウトです。

Added in version 3.13.

呼び出し

モックオブジェクトは呼び出し可能です。呼び出しの戻り値は return_value 属性に設定された値です。デフォルトでは新しいモックオブジェクトを返します。この新しいモックは、属性に最初にアクセスした際に作成されます (明示もしくはモックの呼び出しによって)。 そしてそれは保存され、それ以降は同じものが返されます。

呼び出しはオブジェクトとして call_args や call_args_list に記録されます。

side_effect を設定している場合は、呼び出しを記録した後に実行します。 そのため、side_effect が例外を送出しても、呼び出しは記録されます。

呼び出された際に例外を発生させるモックを作成するためには、 side_effect を例外クラスかインスタンスにする方法が最もシンプルです:

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

side_effect が関数の場合、モックを呼び出すとその関数の戻り値を返します。 side_effect 関数には、モックと同じ引数が渡されます。 これにより、入力に応じて呼び出しの戻り値を動的に変えられます。

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

デフォルトの戻り値 (新しいモック) や、設定した戻り値をそのまま返したい場合は、2 つの方法があります。 side_effect 内から return_value を返すか、DEFAULT を返します。

>>> m = MagicMock()
>>> def side_effect(*args, **kwargs):
...     return m.return_value
...
>>> m.side_effect = side_effect
>>> m.return_value = 3
>>> m()
3
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> m.side_effect = side_effect
>>> m()
3

side_effect を取り除いてデフォルトの動作に戻すには、side_effect を None に設定します。

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

side_effect には任意のイテラブルも指定できます。 モックを繰り返し呼び出すと、イテラブルから値を順に返します (イテラブルが 尽きる と StopIteration を送出します)。

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

属性の削除

モックオブジェクトは要求に応じて属性を生成することで，任意のオブジェクトとして振る舞うことができます。

hasattr() に対して False を返したり、属性を取得しようとすると AttributeError を送出したりするモックオブジェクトが必要な場合があります。 モックの spec にオブジェクトを指定することでも実現できますが、それが常に便利とは限りません。

属性を削除すると、その属性へのアクセスを禁止できます。 削除後にその属性にアクセスすると AttributeError が発生します。

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

Mock の名前と name 属性

"name" は Mock コンストラクタの引数なので、モックオブジェクトが "name" 属性を持つことを望む場合、単に生成時にそれを渡すことはできません。2つの選択肢があります。1つのオプションは configure_mock() を使用することです:

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

より単純なオプションはモックの生成後に単に "name" 属性をセットすることです:

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

属性として設定されるモック

属性 (もしくは戻り値) に他のモックを設定した場合、このモックは "子" になります。この子に対する呼び出しは、親の method_calls や mock_calls に記録されます。これは、子のモックを構成し、親にそのモックを設定する際に有用です。また、親に対して設定したすべての子の呼び出しを記録するため、それらの間の順番を確認する際にも有用です:

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

patch() を用いて作成したモックには、自動的に名前が与えられます。名前を持つモックを設定したい場合には、親に対して attach_mock() メソッドを呼び出します:

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

[1]

例外は特殊メソッドと特殊属性 (名前の先頭と末尾が二重アンダースコアのもの) です。 Mock はこれらを作成せず、AttributeError を送出します。 インタープリタはこれらのメソッドを暗黙的に要求することが多く、特殊メソッドを期待しているのに新しい Mock オブジェクトを受け取ると 大きく 混乱するためです。 特殊メソッドのサポートが必要な場合は 特殊メソッド を参照してください。

patcher

patch デコレータは、デコレートした関数の実行中だけオブジェクトを置き換えるために使います。 例外が発生しても自動的にパッチを解除します。 これらの関数はすべて with 文やクラスデコレータとしても使用できます。

patch

注釈

重要なのは正しい名前空間に対して patch することです。where to patch セクションを参照してください。

unittest.mock.patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

patch() は関数デコレータ、クラスデコレータ、コンテキストマネージャーとして利用できます。関数や with 文の body では、 target は new オブジェクトにパッチされます。関数/with 文が終了すると、パッチは元に戻されます。

new を省略すると、パッチ対象が非同期関数なら AsyncMock、それ以外なら MagicMock に置き換えます。 patch() をデコレータとして使い、new を省略した場合、作成したモックはデコレートした関数に追加の引数として渡されます。 patch() をコンテキストマネージャとして使う場合は、そのコンテキストマネージャが作成したモックを返します。

target は 'package.module.ClassName' の形式の文字列でなければなりません。 target はインポートされ、指定されたオブジェクトが new オブジェクトに置き換えられます。なので、 target は patch() を呼び出した環境からインポート可能でなければなりません。 target がインポートされるのは、デコレートした時ではなく、デコレートされた関数が呼び出された時です。

patch が MagicMock を生成する場合、 spec と spec_set キーワード引数は MagicMock に渡されます。

加えて、 spec=True もしくは spec_set=True を渡すことで、モック対象のオブジェクトが spec/spec_set に渡されます。

new_callable には、new オブジェクトを作成するために呼び出す別のクラスや呼び出し可能オブジェクトを指定できます。 デフォルトでは、非同期関数には AsyncMock、それ以外には MagicMock を使います。

より強力な spec の形は autospec です。 autospec=True を指定した場合、 mock は置換対象となるオブジェクトから得られる spec で生成されます。 mock のすべての属性もまた置換対象となるオブジェクトの属性に応じた spec を持ちます。 mock されたメソッドや関数は引数をチェックし、間違ったシグネチャで呼び出された場合は TypeError を発生させます。クラスを置き換える mock の場合、その戻り値 (つまりインスタンス) はそのクラスと同じ spec を持ちます。 create_autospec() 関数と autospec を使う を参照してください。

置換対象ではなく任意のオブジェクトを spec として使うために、 autospec=True の代わりに、 autospec=some_object と指定することができます。

デフォルトでは、patch() は存在しない属性を置き換えようとすると失敗します。 create=True を渡した場合、属性が存在しなければ、パッチを適用した関数が呼び出されたときにその属性を作成し、関数の終了後に削除します。 製品コードが実行時に作成する属性のテストを書く場合に便利です。 ただし、危険を伴うためデフォルトでは無効になっています。 有効にすると、実際には存在しない API に対して成功するテストを書けてしまいます。

注釈

バージョン 3.5 で変更: モジュールのビルトインにパッチを当てようとしているなら、 create=True を渡す必要はありません。それはデフォルトで追加されます。

patch は TestCase のクラスデコレータとして使えます。 クラス内の各テストメソッドをデコレートすることで機能します。 複数のテストメソッドで共通のパッチを使う場合、定型的なコードを減らせます。 patch() は patch.TEST_PREFIX で始まる名前のメソッドを探してテストを見つけます。 デフォルト値は 'test' で、unittest のテストの探し方と一致します。 patch.TEST_PREFIX を設定して別の接頭辞を指定できます。

patch は with 文を使ってコンテキストマネージャーとして使うこともできます。その場合パッチは with 文のブロック内でのみ適用されます。 "as" を使って、 "as" に続いて指定した変数にパッチされたオブジェクトが代入されます。これは patch() が mock オブジェクトを生成するときに便利です。

patch() は任意のキーワード引数を受け取ります。 これらは、new_callable を指定していればそこへ渡します。 指定していなければ、パッチ対象が非同期の場合は AsyncMock、それ以外は MagicMock に渡します。

異なるユースケースのために、 patch.dict(...), patch.multiple(...), patch.object(...) が用意されています。

patch() を関数デコレータとして利用し、 mock を生成してそれをデコレートされた関数に渡します:

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

クラスをパッチするとそのクラスを MagicMock の インスタンス に置き換えます。テスト中のコードからそのクラスがインスタンス化される場合、 mock の return_value が利用されます。

クラスが複数回インスタンス化される場合、 side_effect を利用して毎回新しい mock を返すようにできます。もしくは、 return_value に、何でも好きなものを設定できます。

パッチを適用したクラスの インスタンス のメソッドに戻り値を設定するには、return_value に対して設定する必要があります。 例えば次のようにします。

>>> class Class:
...     def method(self):
...         pass
...
>>> with patch('__main__.Class') as MockClass:
...     instance = MockClass.return_value
...     instance.method.return_value = 'foo'
...     assert Class() is instance
...     assert Class().method() == 'foo'
...

spec か spec_set を指定し、 patch() が クラス を置換するとき、生成された mock の戻り値は同じ spec を持ちます。:

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

new_callable 引数は、デフォルトの MagicMock の代わりに別のクラスをモックとして生成したい場合に便利です。例えば、 NonCallableMock を利用したい場合:

>>> thing = object()
>>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing:
...     assert thing is mock_thing
...     thing()
...
Traceback (most recent call last):
  ...
TypeError: 'NonCallableMock' object is not callable

別のユースケースとしては、オブジェクトを io.StringIO インスタンスで置き換えることがあります:

>>> from io import StringIO
>>> def foo():
...     print('Something')
...
>>> @patch('sys.stdout', new_callable=StringIO)
... def test(mock_stdout):
...     foo()
...     assert mock_stdout.getvalue() == 'Something\n'
...
>>> test()

patch() に mock を生成させる場合、たいてい最初に必要なことはその mock をセットアップすることです。幾らかのセットアップは patch の呼び出しから行うことができます。任意のキーワード引数が、生成された mock の属性に設定されます:

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

生成された mock の属性のさらに属性、 return_value side_effect などもセットアップできます。これらはキーワード引数のシンタックスでは直接指定できませんが、それらをキーとする辞書を ** を使って patch() に渡すことができます:

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

デフォルトでは、モジュールに存在しない関数 (またはクラスに存在しないメソッドや属性) にパッチを適用しようとすると AttributeError で失敗します。

>>> @patch('sys.non_existing_attribute', 42)
... def test():
...     assert sys.non_existing_attribute == 42
...
>>> test()
Traceback (most recent call last):
  ...
AttributeError: <module 'sys' (built-in)> does not have the attribute 'non_existing_attribute'

ただし、patch() の呼び出しに create=True を追加すると、上の例は期待どおりに動作します。

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

バージョン 3.8 で変更: 対象が非同期関数の場合、patch() は AsyncMock を返すようになりました。

patch.object

patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

オブジェクト (target) の指定された名前のメンバー (attribute) を mock オブジェクトでパッチします。

patch.object() はデコレータ、クラスデコレータ、コンテキストマネージャーとして利用できます。引数の new, spec, create, spec_set, autospec, new_callable は patch() と同じ意味を持ちます。 patch() と同じく、 patch.object() も mock を生成するための任意のキーワード引数を受け取ります。

クラスデコレータとして利用する場合、 patch.object() は patch.TEST_PREFIX にしたがってラップするメソッドを選択します。

patch.object() の呼び出しには3引数の形式と2引数の形式があります。 3引数の場合、 patch 対象のオブジェクト、属性名、その属性を置き換えるオブジェクトを取ります。

2引数の形式では、置き換えるオブジェクトを省略し、生成された mock がデコレート対象となる関数に追加の引数として渡されます:

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

spec, create やその他の patch.object() の引数は patch() の引数と同じ意味を持ちます。

patch.dict

patch.dict(in_dict, values=(), clear=False, **kwargs)

辞書または辞書のようなオブジェクトにパッチを適用し、テスト後に元の状態に戻します。 復元には、テスト前の辞書のコピーを使います。

in_dict は辞書やその他のマップ型のコンテナです。マップ型の場合、最低限 get, set, del 操作とキーに対するイテレートをサポートしている必要があります。

in_dict に辞書を指定する文字列を渡した場合、それをインポートして取得します。

values は対象の辞書にセットする値を含む、辞書か (key, value) ペアの iterable です。

clear が true なら、新しい値が設定される前に辞書がクリアされます。

patch.dict() はまた、任意のキーワード引数を受け取って辞書に設定します。

バージョン 3.8 で変更: patch.dict() をコンテキストマネージャとして使うと、パッチを適用した辞書を返すようになりました。

patch.dict() はコンテキストマネージャ、デコレータ、クラスデコレータとして使えます。

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

クラスデコレータとして使う場合、patch.dict() は patch.TEST_PREFIX (デフォルトは 'test') に従ってラップするメソッドを選びます。

>>> import os
>>> import unittest
>>> from unittest.mock import patch
>>> @patch.dict('os.environ', {'newkey': 'newvalue'})
... class TestSample(unittest.TestCase):
...     def test_sample(self):
...         self.assertEqual(os.environ['newkey'], 'newvalue')

テストに別の接頭辞を使いたい場合は、patch.TEST_PREFIX を設定してパッチ処理に知らせることができます。 値の変更方法の詳細は TEST_PREFIX を参照してください。

patch.dict() を使うと、辞書にメンバーを追加するか、または単にテストが辞書を変更して、その後テストが終了した時にその辞書が確実に復元されるようにすることができます。

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

>>> import os
>>> with patch.dict('os.environ', {'newkey': 'newvalue'}):
...     print(os.environ['newkey'])
...
newvalue
>>> assert 'newkey' not in os.environ

patch.dict() を呼び出すときにキーワード引数を使って辞書に値をセットすることができます。

>>> mymodule = MagicMock()
>>> mymodule.function.return_value = 'fish'
>>> with patch.dict('sys.modules', mymodule=mymodule):
...     import mymodule
...     mymodule.function('some', 'args')
...
'fish'

patch.dict() can be used with dictionary like objects that aren't actually dictionaries. At the very minimum they must support item getting, setting, deleting and either iteration or membership test. This corresponds to the magic methods __getitem__(), __setitem__(), __delitem__() and either __iter__() or __contains__().

>>> class Container:
...     def __init__(self):
...         self.values = {}
...     def __getitem__(self, name):
...         return self.values[name]
...     def __setitem__(self, name, value):
...         self.values[name] = value
...     def __delitem__(self, name):
...         del self.values[name]
...     def __iter__(self):
...         return iter(self.values)
...
>>> thing = Container()
>>> thing['one'] = 1
>>> with patch.dict(thing, one=2, two=3):
...     assert thing['one'] == 2
...     assert thing['two'] == 3
...
>>> assert thing['one'] == 1
>>> assert list(thing) == ['one']

patch.multiple

patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

1回の呼び出しで複数のパッチを実行します。パッチ対象のオブジェクト (あるいはそのオブジェクトをインポートするための文字列) と、パッチ用のキーワード引数を取ります:

with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
    ...

patch.multiple() に mock を生成させたい場合、キーワード引数の値に DEFAULT を指定します。この場合生成されたモックはデコレート対象の関数にキーワード引数として渡され、コンテキストマネージャーとして patch.multiple() が利用された場合は辞書として返します。

patch.multiple() はデコレータ、クラスデコレータ、コンテキストマネージャーとして使えます。引数の spec, spec_set, create, autospec, new_callable は patch() の引数と同じ意味を持ちます。これらの引数は patch.multiple() によって適用される すべての パッチに対して適用されます。

クラスデコレータとして利用する場合、 patch.multiple() は patch.TEST_PREFIX にしたがってラップするメソッドを選択します。

patch.multiple() に mock を生成させたい場合、キーワード引数の値に DEFAULT を指定します。patch.multiple() をデコレータとして使った場合生成されたモックはデコレート対象の関数にキーワード引数として渡されます。:

>>> thing = object()
>>> other = object()

>>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(thing, other):
...     assert isinstance(thing, MagicMock)
...     assert isinstance(other, MagicMock)
...
>>> test_function()

patch.multiple() は他の patch デコレータとネストして利用できますが、キーワード引数は patch() によって作られる通常の引数の 後ろ で受け取る必要があります:

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

patch.multiple() がコンテキストマネージャーとして利用される場合、コンテキストマネージャーが返す値は、名前がキーで値が生成された mock となる辞書です:

>>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values:
...     assert 'other' in repr(values['other'])
...     assert 'thing' in repr(values['thing'])
...     assert values['thing'] is thing
...     assert values['other'] is other
...

patch のメソッド: start と stop

すべてのパッチ処理オブジェクトには start() メソッドと stop() メソッドがあります。 setUp メソッド内でパッチを適用したい場合や、デコレータや with 文を入れ子にせず複数のパッチを適用したい場合に便利です。

これらを使うには、通常どおり patch()、patch.object()、patch.dict() のいずれかを呼び出し、戻り値の patcher オブジェクトへの参照を保持します。 その後、start() を呼び出してパッチを適用し、stop() を呼び出して元に戻せます。

patch() に mock を生成させる場合、 patcher.start の呼び出しの戻り値として mock を受け取れます。:

>>> patcher = patch('package.module.ClassName')
>>> from package import module
>>> original = module.ClassName
>>> new_mock = patcher.start()
>>> assert module.ClassName is not original
>>> assert module.ClassName is new_mock
>>> patcher.stop()
>>> assert module.ClassName is original
>>> assert module.ClassName is not new_mock

典型的な用途として、TestCase の setUp メソッド内で複数のパッチを適用する場合が挙げられます。

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher1 = patch('package.module.Class1')
...         self.patcher2 = patch('package.module.Class2')
...         self.MockClass1 = self.patcher1.start()
...         self.MockClass2 = self.patcher2.start()
...
...     def tearDown(self):
...         self.patcher1.stop()
...         self.patcher2.stop()
...
...     def test_something(self):
...         assert package.module.Class1 is self.MockClass1
...         assert package.module.Class2 is self.MockClass2
...
>>> MyTest('test_something').run()

注意

この方式を使う場合、必ず stop メソッドを呼び出してパッチが解除する必要があります。 setUp の中で例外が発生した場合 tearDown が呼び出されないので、これは意外に面倒です。 unittest.TestCase.addCleanup() を使うと簡単にできます:

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         patcher = patch('package.module.Class')
...         self.MockClass = patcher.start()
...         self.addCleanup(patcher.stop)
...
...     def test_something(self):
...         assert package.module.Class is self.MockClass
...

この方式を使うと patcher オブジェクトの参照を維持する必要がなくなるという特典も付きます。

patch.stopall() を利用してすべての start されたパッチを stop することもできます。

patch.stopall()

すべての有効なパッチを stop します。 start で開始したパッチしか stop しません。

ビルトインをパッチする

モジュール内の任意のビルトインに対してパッチを当てることができます。以下の例はビルトインの ord() を修正します:

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

TEST_PREFIX

すべての patcher はクラスデコレータとして利用できます。この場合、そのクラスのすべてのテストメソッドをラップします。 patcher は 'test' で始まる名前のメソッドをテストメソッドだと認識します。これはデフォルトで unittest.TestLoader がテストメソッドを見つける方法と同じです。

他の prefix を使う事もできます。その場合、 patcher にその prefix を patch.TEST_PREFIX に設定することで教えることができます:

>>> patch.TEST_PREFIX = 'foo'
>>> value = 3
>>>
>>> @patch('__main__.value', 'not three')
... class Thing:
...     def foo_one(self):
...         print(value)
...     def foo_two(self):
...         print(value)
...
>>>
>>> Thing().foo_one()
not three
>>> Thing().foo_two()
not three
>>> value
3

patch デコレータをネストする

複数のパッチを行いたい場合、シンプルにデコレータを重ねることができます。

次のパターンのように patch デコレータを重ねることができます:

>>> @patch.object(SomeClass, 'class_method')
... @patch.object(SomeClass, 'static_method')
... def test(mock1, mock2):
...     assert SomeClass.static_method is mock1
...     assert SomeClass.class_method is mock2
...     SomeClass.static_method('foo')
...     SomeClass.class_method('bar')
...     return mock1, mock2
...
>>> mock1, mock2 = test()
>>> mock1.assert_called_once_with('foo')
>>> mock2.assert_called_once_with('bar')

デコレータは下から上へと適用されることに注意してください。これは Python がデコレータを適用する標準的な方法です。テスト関数に渡される生成された mock の順番もこれに一致します。

どこにパッチするか

patch() は (一時的に) ある 名前 が参照しているオブジェクトを別のものに変更することで適用されます。任意のオブジェクトには、それを参照するたくさんの名前が存在しえます。なので、必ずテスト対象のシステムが使っている名前に対して patch しなければなりません。

基本的な原則は、オブジェクトが ルックアップ されるところにパッチすることです。その場所はオブジェクトが定義されたところとは限りません。これを説明するためにいくつかの例を挙げます。

次のような構造を持ったプロジェクトをテストしようとしていると仮定してください:

a.py
    -> SomeClass を定義する

b.py
    -> from a import SomeClass
    -> some_function が SomeClass をインスタンス化する

ここで some_function をテストするため、patch() で SomeClass をモックに置き換えたいとします。 問題は、テストに必要なモジュール b をインポートすると、b がモジュール a から SomeClass をインポートすることです。 patch() で a.SomeClass をモックに置き換えても、テストには影響しません。 モジュール b はすでに 本物の SomeClass への参照を持っているため、パッチが効いていないように見えます。

重要なのは、 SomeClass が使われている (もしくはルックアップされている) 場所にパッチすることです。この場合、 some_function はモジュール b の中にインポートされた SomeClass をルックアップしています。なのでパッチは次のようにしなければなりません:

@patch('b.SomeClass')

ですが、別のシナリオとして、module b が from a import SomeClass ではなく import a をしていて、 some_function が a.SomeClass を利用していたとします。どちらのインポートも一般的なものです。この場合、パッチしたいクラスはそのモジュールからルックアップされているので、 a.SomeClass をパッチする必要があります:

@patch('a.SomeClass')

デスクリプタやプロキシオブジェクトにパッチする

patch と patch.object はどちらも デスクリプタ (クラスメソッド、static メソッド、プロパティ) を正しく patch できます。デスクリプタに patch する場合、インスタンスではなく class にパッチする必要があります。これらはまた 幾らかの 属性アクセスをプロキシするオブジェクト、例えば django の setttings オブジェクト に対しても機能します。

MagicMock と magic method のサポート

Magic Method をモックする

Mock は、特殊メソッド とも呼ばれる Python のプロトコルメソッドのモックをサポートしています。 これにより、コンテナや、Python のプロトコルを実装した他のオブジェクトをモックオブジェクトで置き換えられます。

magic method は通常のメソッドとはルックアップ方法が異なるので [2], magic method のサポートは特別に実装されています。そのため、サポートされているのは特定の magic method のみです。ほとんど すべてのメソッドをサポートしていますが、足りないものを見つけたら私達に教えてください。

magic method を mock するには、対象の method に対して関数や mock のインスタンスをセットします。もし関数を使う場合、それは第一引数に self を取る 必要があります [3].

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

ユースケースの1つは with 文の中でコンテキストマネージャーとして使われるオブジェクトを mock することです。

>>> mock = Mock()
>>> mock.__enter__ = Mock(return_value='foo')
>>> mock.__exit__ = Mock(return_value=False)
>>> with mock as m:
...     assert m == 'foo'
...
>>> mock.__enter__.assert_called_with()
>>> mock.__exit__.assert_called_with(None, None, None)

magic method の呼び出しは method_calls に含まれませんが、 mock_calls には記録されます。

注釈

mock を生成するのに spec キーワード引数を使った場合、 spec に含まれない magic method を設定しようとすると AttributeError が発生します。

サポートしている magic method の完全なリスト:

• __hash__, __sizeof__, __repr__, __str__

• __dir__, __format__, __subclasses__

• __round__, __floor__, __trunc__ と __ceil__

• 比較: __lt__, __gt__, __le__, __ge__, __eq__, __ne__

• コンテナメソッド: __getitem__, __setitem__, __delitem__, __contains__, __len__, __iter__, __reversed__, __missing__

• コンテキストマネージャ: __enter__、__exit__、__aenter__、__aexit__

• 単項算術メソッド: __neg__, __pos__, __invert__

• 数値演算メソッド (右側のオペランド用とインプレース演算用のものも含む): __add__、__sub__、__mul__、__matmul__、__truediv__、__floordiv__、__mod__、__divmod__、__lshift__、__rshift__、__and__、__xor__、__or__、__pow__

• 算術変換メソッド: __complex__, __int__, __float__, __index__

• デスクリプタメソッド: __get__, __set__, __delete__

• pickle: __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__, __setstate__

• ファイルシステムのパス表現: __fspath__

• 非同期イテレーションのメソッド: __aiter__、__anext__

バージョン 3.8 で変更: os.PathLike.__fspath__() に対応しました。

バージョン 3.8 で変更: __aenter__、__aexit__、__aiter__、__anext__ に対応しました。

以下のメソッドは存在しますが、mock が利用している、動的に設定不可能、その他の問題が発生する可能性があるなどの理由で サポートされていません:

• __getattr__, __setattr__, __init__, __new__

• __prepare__, __instancecheck__, __subclasscheck__, __del__

Magic Mock

MagicMock 系のクラスは2種類あります: MagicMock と NonCallableMagicMock です。

class unittest.mock.MagicMock(*args, **kw)

MagicMock は、特殊メソッド の大半についてデフォルトの実装を備えた Mock のサブクラスです。 特殊メソッドを自分で設定せずに MagicMock を使えます。

コンストラクタの引数は Mock と同じ意味を持っています。

spec か spec_set 引数を利用した場合、 spec に存在する magic method のみ が生成されます。

class unittest.mock.NonCallableMagicMock(*args, **kw)

callable でないバージョンの MagicMock

コンストラクタの引数は MagicMock と同じ意味を持ちますが、 return_value と side_effect は callable でない mock では意味を持ちません。

MagicMock が magic method をセットアップするので、あとは通常の方法で構成したり利用したりできます:

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

デフォルトでは、多くのプロトコルメソッドは特定の型の戻り値を要求されます。それらのメソッドではその型のデフォルトの戻り値がデフォルトの戻り値として設定されているので、戻り値に興味が有る場合以外は何もしなくても利用可能です。デフォルトの値を変更したい場合は手動で戻り値を設定可能です。

メソッドとそのデフォルト値:

• __lt__: NotImplemented

• __gt__: NotImplemented

• __le__: NotImplemented

• __ge__: NotImplemented

• __int__: 1

• __contains__: False

• __len__: 0

• __iter__: iter([])

• __exit__: False

• __aexit__: False

• __complex__: 1j

• __float__: 1.0

• __bool__: True

• __index__: 1

• __hash__: mock のデフォルトの hash

• __str__: mock のデフォルトの str

• __sizeof__: mock のデフォルトの sizeof

例えば:

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

等価性を比較する 2 つのメソッド __eq__() と __ne__() は特別です。 戻り値を別の値に変更しない限り、side_effect 属性を使って、オブジェクトの同一性に基づくデフォルトの等価性比較を行います。

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

__iter__() の戻り値には任意のイテラブルを指定でき、イテレータである必要はありません。

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

return_value が iterator であった場合、最初のイテレートでその iterator を消費してしまい、2回目以降のイテレートの結果が空になってしまいます:

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

MagicMock では、あまり使われないものや廃れたものの一部を除き、サポートしている特殊メソッドがすべて設定済みです。 必要であれば、それらのメソッドも設定できます。

MagicMock がサポートしているもののデフォルトではセットアップしない magic method:

• __subclasses__

• __dir__

• __format__

• __get__, __set__, __delete__

• __reversed__, __missing__

• __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__, __setstate__

• __getformat__

[2]

Magic method はインスタンスではなくクラスからルックアップされるはずです。Python のバージョンによってこのルールが適用されるかどうかに違いがあります。サポートされているプロトコルメソッドは、サポートされているすべての Python のバージョンで動作するはずです。

[3]

関数はクラスまで hook しますが、各 Mock インスタンス間の独立性は保たれます。

ヘルパー

sentinel

unittest.mock.sentinel

sentinel オブジェクトはテストで必要なユニークなオブジェクトを簡単に提供します。

属性はアクセス時にオンデマンドで生成されます。同じ属性に複数回アクセスすると必ず同じオブジェクトが返されます。返されるオブジェクトは、テスト失敗のメッセージがわかりやすくなるように気が利いた repr を持ちます。

バージョン 3.7 で変更: sentinel の属性は、コピー や pickle 化 の際にも同一性を保つようになりました。

特定のオブジェクトが他のメソッドに引数として渡されることをテストしたり、返されることをテストしたい場合があります。このテストのために名前がついた sentinel オブジェクトを作るのが一般的です。 sentinel はこのようなオブジェクトを生成し、同一性をテストするのに便利な方法を提供します。

次の例では、 method が sentinel.some_object を返すようにモンキーパッチしています:

>>> real = ProductionClass()
>>> real.method = Mock(name="method")
>>> real.method.return_value = sentinel.some_object
>>> result = real.method()
>>> assert result is sentinel.some_object
>>> result
sentinel.some_object

DEFAULT

unittest.mock.DEFAULT

DEFAULT オブジェクトは事前に生成された sentinel (実際には sentinel.DEFAULT) オブジェクトです。 side_effect 関数が、通常の戻り値を使うことを示すために使います。

call

unittest.mock.call(*args, **kwargs)

call() は call_args, call_args_list, mock_calls, method_calls と比較してより簡単に assert できるようにするためのヘルパーオブジェクトです。 call() は assert_has_calls() と組み合わせて使うこともできます。

>>> m = MagicMock(return_value=None)
>>> m(1, 2, a='foo', b='bar')
>>> m()
>>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
True

call.call_list()

複数回の呼び出しを表す call オブジェクトに対して、 call_list() はすべての途中の呼び出しと最終の呼び出しを含むリストを返します。

call_list は特に "chained call" に対して assert するのに便利です。 "chained call" は1行のコードにおける複数の呼び出しです。この結果は mock の mock_calls に複数の call エントリとして格納されます。この call のシーケンスを手動で構築するのは退屈な作業になります。

call_list() は同じ chained call からその call のシーケンスを構築することができます:

>>> m = MagicMock()
>>> m(1).method(arg='foo').other('bar')(2.0)
<MagicMock name='mock().method().other()()' id='...'>
>>> kall = call(1).method(arg='foo').other('bar')(2.0)
>>> kall.call_list()
[call(1),
 call().method(arg='foo'),
 call().method().other('bar'),
 call().method().other()(2.0)]
>>> m.mock_calls == kall.call_list()
True

call オブジェクトは、どう構築されたかによって、 (位置引数、キーワード引数) のタプルか、 (名前、位置引数、キーワード引数) のタプルになります。自分で call オブジェクトを構築するときはこれを意識する必要はありませんが、 Mock.call_args, Mock.call_args_list, Mock.mock_calls 属性の中の call オブジェクトを解析して個々の引数を解析することができます。

Mock.call_args と Mock.call_args_list の中の call オブジェクトは (位置引数, キーワード引数) のタプルで、 Mock.mock_calls の中の call オブジェクトや自分で構築したオブジェクトは (名前, 位置引数, キーワード引数) のタプルになります。

call オブジェクトの "タプル性" を使って、より複雑な内省とアサートを行うために各引数を取り出しすことができます。位置引数はタプル (位置引数が存在しない場合は空のタプル) で、キーワード引数は辞書になります:

>>> m = MagicMock(return_value=None)
>>> m(1, 2, 3, arg='one', arg2='two')
>>> kall = m.call_args
>>> kall.args
(1, 2, 3)
>>> kall.kwargs
{'arg': 'one', 'arg2': 'two'}
>>> kall.args is kall[0]
True
>>> kall.kwargs is kall[1]
True

>>> m = MagicMock()
>>> m.foo(4, 5, 6, arg='two', arg2='three')
<MagicMock name='mock.foo()' id='...'>
>>> kall = m.mock_calls[0]
>>> name, args, kwargs = kall
>>> name
'foo'
>>> args
(4, 5, 6)
>>> kwargs
{'arg': 'two', 'arg2': 'three'}
>>> name is m.mock_calls[0][0]
True

create_autospec

unittest.mock.create_autospec(spec, spec_set=False, instance=False, **kwargs)

他のオブジェクトを spec として利用して mock オブジェクトを作ります。 mock の属性も、 spec オブジェクトの該当する属性を spec として利用します。

mock された関数やメソッドは、正しいシグネチャで呼び出されたことを確認するために引数をチェックします。

spec_set が True のとき、 spec オブジェクトにない属性をセットしようとすると AttributeError を発生させます。

spec にクラスが指定された場合、 mock の戻り値 (そのクラスのインスタンス) は同じ spec を持ちます。 instance=True を指定すると、インスタンスオブジェクトの spec としてクラスを利用できます。返される mock は、モックのインスタンスが callable な場合にだけ callable となります。

create_autospec() は任意のキーワード引数を受け取り、生成する mock のコンストラクタに渡します。

create_autospec() や、 patch() の autospec 引数で autospec を使うサンプルは autospec を使う を参照してください。

バージョン 3.8 で変更: create_autospec() now returns an AsyncMock if the target is an async function.

ANY

unittest.mock.ANY

mock の呼び出しのうち 幾つか の引数に対して assert したいけれども、それ以外の引数は気にしない、あるいは call_args から個別に取り出してより高度な assert を行いたい場合があります。

特定の引数を無視するために、 すべて と等しくなるオブジェクトを使うことができます。そうすると、 assert_called_with() と assert_called_once_with() は、実際の引数が何であったかに関わらず成功します。

>>> mock = Mock(return_value=None)
>>> mock('foo', bar=object())
>>> mock.assert_called_once_with('foo', bar=ANY)

ANY は mock_calls のような呼び出しリストとの比較にも使えます。

>>> m = MagicMock(return_value=None)
>>> m(1)
>>> m(1, 2)
>>> m(object())
>>> m.mock_calls == [call(1), call(1, 2), ANY]
True

ANY は call オブジェクトとの比較に限らず、テストのアサートにも使えます。

class TestStringMethods(unittest.TestCase):

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', ANY])

FILTER_DIR

unittest.mock.FILTER_DIR

FILTER_DIR は mock オブジェクトが dir() に何を返すかを制御するためのモジュールレベル変数です。デフォルトは True で、以下に示すフィルタリングを行い、有用なメンバーだけを表示します。このフィルタリングが嫌な場合や、何かの診断のためにフィルタリングを切りたい場合は、 mock.FILTER_DIR = False と設定してください。

フィルタリングが有効な場合、 dir(some_mock) は有用な属性だけを表示し、また通常は表示されない動的に生成される属性も表示します。 mock が spec を使って(もちろん autospec でも)生成された場合、元のオブジェクトのすべての属性が、まだアクセスされていなかったとしても、表示されます。

>>> dir(Mock())
['assert_any_call',
 'assert_called',
 'assert_called_once',
 'assert_called_once_with',
 'assert_called_with',
 'assert_has_calls',
 'assert_not_called',
 'attach_mock',
 ...
>>> from urllib import request
>>> dir(Mock(spec=request))
['AbstractBasicAuthHandler',
 'AbstractDigestAuthHandler',
 'AbstractHTTPHandler',
 'BaseHandler',
 ...

多くのあまり有用ではない (mock 対象のものではなく、 Mock 自身のプライベートな) 属性は、アンダースコアと2つのアンダースコアで prefix された属性は Mock に対して dir() した結果からフィルタリングされます。この動作が嫌な場合は、モジュールレベルの FILTER_DIR スイッチを設定することでフィルターを切ることができます。

>>> from unittest import mock
>>> mock.FILTER_DIR = False
>>> dir(mock.Mock())
['_NonCallableMock__get_return_value',
 '_NonCallableMock__get_side_effect',
 '_NonCallableMock__return_value_doc',
 '_NonCallableMock__set_return_value',
 '_NonCallableMock__set_side_effect',
 '__call__',
 '__class__',
 ...

また、vars(my_mock) (インスタンスのメンバー) と dir(type(my_mock)) (型のメンバー) を使えば、FILTER_DIR の値にかかわらずフィルタリングを回避できます。

mock_open

unittest.mock.mock_open(mock=None, read_data='')

open() の利用を置き換えるための mock を作るヘルパー関数。 open() を直接呼んだりコンテキストマネージャーとして利用する場合に使うことができます。

mock 引数は構成する mock オブジェクトです。 None (デフォルト) なら、通常のファイルハンドルと同じ属性やメソッドにAPIが制限された MagicMock が生成されます。

read_data は、ファイルハンドルの read()、readline()、readlines() メソッドが返す文字列です。 これらのメソッドを呼び出すと、read_data が尽きるまでデータを取り出します。 これらのメソッドのモックは単純なもので、mock を呼び出すたびに read_data の読み取り位置が先頭に戻ります。 テスト対象のコードに渡すデータをもっと細かく制御したい場合は、このモックを自分でカスタマイズする必要があります。 それでも不十分な場合は、PyPI にあるメモリ上のファイルシステムを実装したパッケージを使うと、テスト用の現実的なファイルシステムを用意できます。

バージョン 3.4 で変更: readline() と readlines() に対応しました。 read() のモックは、呼び出しのたびに read_data をそのまま返すのではなく、消費するようになりました。

バージョン 3.5 で変更: read_data は mock を呼び出す度に毎回リセットされるようになりました。

バージョン 3.8 で変更: 実装に __iter__() を追加し、for ループなどのイテレーションで read_data が正しく消費されるようになりました。

open() をコンテキストマネージャーとして使う方法は、ファイルが必ず適切に閉じられるようにする素晴らしい方法で、今では一般的になっています:

with open('/some/path', 'w') as f:
    f.write('something')

open() の呼び出しをモックに置き換えても、コンテキストマネージャとして使われるのは 戻り値のオブジェクト である点に注意が必要です (__enter__() と __exit__() が呼び出されるのもそのオブジェクトです)。

コンテキストマネージャーを MagicMock でモックするのは一般的かつ面倒なので、ヘルパー関数を用意しています。:

>>> m = mock_open()
>>> with patch('__main__.open', m):
...     with open('foo', 'w') as h:
...         h.write('some stuff')
...
>>> m.mock_calls
[call('foo', 'w'),
 call().__enter__(),
 call().write('some stuff'),
 call().__exit__(None, None, None)]
>>> m.assert_called_once_with('foo', 'w')
>>> handle = m()
>>> handle.write.assert_called_once_with('some stuff')

ファイルの読み込みをモックする例:

>>> with patch('__main__.open', mock_open(read_data='bibble')) as m:
...     with open('foo') as h:
...         result = h.read()
...
>>> m.assert_called_once_with('foo')
>>> assert result == 'bibble'

autospec を使う

autospec は、既存のモックの spec 機能を基盤にしています。 モックの API を元のオブジェクト (spec) の API に制限しますが、これを再帰的に行う (遅延処理で実装されている) ため、 モックの属性も spec の対応する属性と同じ API だけを持ちます。 さらに、モックに置き換えた関数やメソッドは元と同じ呼び出しシグネチャを持ち、誤った呼び出しに対して TypeError を送出します。

autospec の動作について説明する前に、それが必要となる背景から説明していきます。

Mock は非常に強力で柔軟なオブジェクトですが、モックに共通する弱点があります。 コードの一部をリファクタリングしてメンバーの名前を変更しても、 古い API を使い続けているコードのテストで本物のオブジェクトの代わりにモックを使っていると、テストは成功し続けます。 つまり、コードが壊れていてもテストがすべて成功する可能性があります。

バージョン 3.5 で変更: 3.5 より前では、assert の綴りを間違えたテストが、エラーになるべきなのに何も知らせず成功していました。 Mock に unsafe=True を渡すと、今でもこの動作にできます。

これも、単体テストだけでなく結合テストが必要な理由の 1 つです。 すべてを個別にテストするのはよいことですが、各部分が「どうつながるか」をテストしなければ、 テストで発見できたはずのバグが入り込む余地が依然として多く残ります。

unittest.mock は、この問題に役立つ spec という機能をすでに提供しています。 モックの spec にクラスやインスタンスを指定すると、モックでは本物のクラスに存在する属性にしかアクセスできません。

>>> from urllib import request
>>> mock = Mock(spec=request.Request)
>>> mock.assret_called_with  # Intentional typo!
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'

spec はその mock 自体にしか適用されません。なので、同じ問題がその mock のすべてのメソッドに対して発生します:

>>> mock.header_items()
<mock.Mock object at 0x...>
>>> mock.header_items.assret_called_with()  # Intentional typo!

autospec はこの問題を解決します。 patch() か patch.object() に autospec=True を渡すか、 create_autospec() 関数を使って spec をもとに mock を作ることができます。 patch() の引数に autospec=True を渡した場合、置換対象のオブジェクトが spec オブジェクトとして利用されます。 spec は遅延処理される (mock の属性にアクセスされた時に spec が生成される) ので、非常に複雑だったり深くネストしたオブジェクト (例えばモジュールをインポートするモジュールをインポートするモジュール) に対しても大きなパフォーマンスの問題なしに autospec を使うことができます。

autospec の利用例:

>>> from urllib import request
>>> patcher = patch('__main__.request', autospec=True)
>>> mock_request = patcher.start()
>>> request is mock_request
True
>>> mock_request.Request
<MagicMock name='request.Request' spec='Request' id='...'>

request.Request に spec が設定されていることがわかります。 request.Request のコンストラクタには 2 つの必須引数があり、そのうち 1 つは self です。 誤った呼び出しをすると、次のようになります。

>>> req = request.Request()
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes at least 2 arguments (1 given)

spec はクラスがインスタンス化されたとき (つまり spec が適用された mock の戻り値) にも適用されます:

>>> req = request.Request('foo')
>>> req
<NonCallableMagicMock name='request.Request()' spec='Request' id='...'>

Request オブジェクトは呼び出し可能ではないため、モックに置き換えた request.Request をインスタンス化した結果も、呼び出し不可能なモックになります。 spec を設定しておくと、アサートの綴りを間違えた場合に適切なエラーが発生します。

>>> req.add_header('spam', 'eggs')
<MagicMock name='request.Request().add_header()' id='...'>
>>> req.add_header.assret_called_with  # 意図的な綴り間違いです。
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'
>>> req.add_header.assert_called_with('spam', 'eggs')

多くの場合、単に既存の patch() 呼び出しに autospec=True を加えるだけで、ミススペルやAPI変更に伴うバグから守られます。

patch() を経由する以外にも、 create_autospec() を使って autospec が適用された mock を直接作る方法もあります:

>>> from urllib import request
>>> mock_request = create_autospec(request)
>>> mock_request.Request('foo', 'bar')
<NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>

ただし、注意点や制限があるため、これはデフォルトの動作にはなっていません。 spec オブジェクトで使える属性を知るには、autospec は spec を調べる (属性にアクセスする) 必要があります。 モックの属性をたどると、内部では元のオブジェクトの対応する属性もたどります。 spec に指定したオブジェクトに、コードの実行を引き起こすプロパティやデスクリプタがある場合は、autospec を使えないことがあります。 一方で、こうした内部調査を安全に行えるようにオブジェクトを設計する方が望ましいでしょう [4]。

さらに大きな問題は、インスタンス属性を __init__() メソッド内で作成し、クラス自体には持たせないことがよくある点です。 autospec は動的に作成される属性を把握できず、API を見える属性に制限します。

>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a
...
Traceback (most recent call last):
  ...
AttributeError: Mock object has no attribute 'a'

この問題を解決するためにいくつかの方法があります。 一番簡単な、ただし一番面倒でないとは限らない方法は、必要とされる属性を mock が生成された後に設定することです。 autospec は spec に存在しない属性の取得を禁止しますが、その属性の設定は禁止しません:

>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a = 33
...

spec と autospec にはよりアグレッシブなバージョンがあり、存在しない属性への設定も禁止します。これはコードが正しい属性にのみ代入することを保証したいときに便利ですが、もちろん先ほどの方法も制限されてしまいます:

>>> with patch('__main__.Something', autospec=True, spec_set=True):
...   thing = Something()
...   thing.a = 33
...
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'a'

おそらく最善の解決策は、__init__() で初期化するインスタンスのメンバーに、デフォルト値としてクラス属性を追加することです。 __init__() で属性にデフォルト値を設定するだけなら、クラス属性として用意する (もちろんインスタンス間で共有されます) 方が速くもなります。 例えば次のようにします。

class Something:
    a = 33

クラス属性を使ってもまた別の問題があります。メンバーのデフォルト値に None を利用し、後から別の型のオブジェクトを代入するのは比較的よくあるパターンです。 spec として None を使うと すべての 属性やメソッドへのアクセスも許されなくなるので使い物になりません。 None を spec にすることが有用な場面は 決して なく、おそらくそのメンバーは他の何かの型のメンバーになることを示すので、 autospec は None に設定されているメンバーには spec を使いません。その属性は通常の mock (MagicMocks) になります。

>>> class Something:
...     member = None
...
>>> mock = create_autospec(Something)
>>> mock.member.foo.bar.baz()
<MagicMock name='mock.member.foo.bar.baz()' id='...'>

すでに利用されているクラスにデフォルト値属性を追加するのが嫌な場合は、他の選択肢もあります。選択肢の1つは、クラスではなくインスタンスを spec に使うことです。別の選択肢は、実際のクラスのサブクラスを作り、実際に利用されている方に影響を与えずにデフォルト値属性を追加することです。どちらの方法も spec として代替オブジェクトを利用することが必要です。 patch() はこれをサポートしていて、 autospec 引数に代替オブジェクトを渡すことができます:

>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> class SomethingForTest(Something):
...   a = 33
...
>>> p = patch('__main__.Something', autospec=SomethingForTest)
>>> mock = p.start()
>>> mock.a
<NonCallableMagicMock name='Something.a' spec='int' id='...'>

[4]

これはクラスやすでにインスタンス化されたオブジェクトにだけ当てはまります。 mock されたクラスを呼び出して mock インスタンスを作っても、実際のオブジェクトのインスタンスは生成されません。 mock は属性を - dir() を呼び出して - 検索するだけです。

モックの封印

unittest.mock.seal(mock)

seal は、封印するモックの属性にアクセスした際のモックの自動作成を無効にします。 すでにモックになっている属性についても再帰的に同じ処理を行います。

名前または spec を持つモックインスタンスを属性に代入した場合、そのモックは再帰的な封印の対象になりません。 これにより、モックオブジェクトの一部が seal で固定されるのを防げます。

>>> mock = Mock()
>>> mock.submock.attribute1 = 2
>>> mock.not_submock = mock.Mock(name="sample_name")
>>> seal(mock)
>>> mock.new_attribute  # AttributeError が発生します。
>>> mock.submock.attribute2  # AttributeError が発生します。
>>> mock.not_submock.attribute2  # 例外は発生しません。

Added in version 3.7.

side_effect、return_value、wraps の優先順位

優先順位は次のとおりです。

1. side_effect

2. return_value

3. wraps

3 つすべてを設定すると、モックは return_value とラップしたオブジェクトをどちらも無視し、side_effect から得た値を返します。 2 つを設定した場合は、優先順位が高い方から値を返します。 どれを先に設定したかにかかわらず、優先順位は変わりません。

>>> from unittest.mock import Mock
>>> class Order:
...     @staticmethod
...     def get_value():
...         return "third"
...
>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.get_value.side_effect = ["first"]
>>> order_mock.get_value.return_value = "second"
>>> order_mock.get_value()
'first'

side_effect のデフォルト値は None なので、値を None に戻すと、 side_effect は無視され、return_value とラップしたオブジェクトの間で優先順位が判断されます。

>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'

side_effect が返す値が DEFAULT の場合、その値は無視され、優先順位が次のものから戻り値を取得します。

>>> from unittest.mock import DEFAULT
>>> order_mock.get_value.side_effect = [DEFAULT]
>>> order_mock.get_value()
'second'

Mock がオブジェクトをラップする場合、return_value のデフォルト値は DEFAULT になります。

>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.return_value
sentinel.DEFAULT
>>> order_mock.get_value.return_value
sentinel.DEFAULT

この値は優先順位の判断で無視され、最後の候補であるラップしたオブジェクトに進みます。

ラップしたオブジェクトが実際に呼び出されるため、このモックをインスタンス化すると、そのクラスの本物のインスタンスを返します。 ラップしたオブジェクトが位置引数を必要とする場合は、それらを渡す必要があります。

>>> order_mock_instance = order_mock()
>>> isinstance(order_mock_instance, Order)
True
>>> order_mock_instance.get_value()
'third'

>>> order_mock.get_value.return_value = DEFAULT
>>> order_mock.get_value()
'third'

>>> order_mock.get_value.return_value = "second"
>>> order_mock.get_value()
'second'

ただし、None を代入した場合は明示的な代入なので無視されません。 そのため、ラップしたオブジェクトには進みません。

>>> order_mock.get_value.return_value = None
>>> order_mock.get_value() is None
True

モックの初期化時に 3 つすべてを一度に設定しても、優先順位は変わりません。

>>> order_mock = Mock(spec=Order, wraps=Order,
...                   **{"get_value.side_effect": ["first"],
...                      "get_value.return_value": "second"}
...                   )
...
>>> order_mock.get_value()
'first'
>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'
>>> order_mock.get_value.return_value = DEFAULT
>>> order_mock.get_value()
'third'

side_effect が 尽きた 場合は、優先順位が次のものから値を取得することはありません。 代わりに StopIteration 例外を送出します。

>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.get_value.side_effect = ["first side effect value",
...                                     "another side effect value"]
>>> order_mock.get_value.return_value = "second"

>>> order_mock.get_value()
'first side effect value'
>>> order_mock.get_value()
'another side effect value'

>>> order_mock.get_value()
Traceback (most recent call last):
 ...
StopIteration