# `unittest.mock` --- mock object library

バージョン 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' パターンに基づいています。

There is a backport of `unittest.mock` for earlier versions of Python, available as mock on PyPI.

## クイックガイド

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

    >>> 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: <lambda>() takes exactly 3 arguments (1 given)

`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: By default, accessing any attribute whose name starts with assert, assret, asert, aseert or assrt will raise an `AttributeError`. Passing `unsafe=True` will allow access to these attributes.

    バージョン 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()

    バージョン 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.

    バージョン 3.6 で追加.

  assert_called_with(*args, **kwargs)

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

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

  assert_called_once_with(*args, **kwargs)

    モックが一度だけ呼び出され、かつ指定された引数で呼び出されたことをアサートします。

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

  assert_any_call(*args, **kwargs)

    モックが特定の引数で呼び出されたことがあるのをアサートします。

    The assert passes if the mock has ever been called, unlike `assert_called_with()` and `assert_called_once_with()` that only pass if the call is the most recent one, and in the case of `assert_called_once_with()` it must also be the only call.

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

  assert_has_calls(calls, any_order=False)

    モックが特定の呼び出しで呼ばれたことをアサートします。呼び出しでは `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.

    バージョン 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

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

    This can be useful where you want to make a series of assertions that reuse the same object. Note that `reset_mock()` doesn't clear the return value, `side_effect` or any child attributes you have set using normal assignment by default. In case you want to reset return_value or `side_effect`, then pass the corresponding parameter as `True`. Child mocks and the return value mock (if any) are reset as well.

    注釈

    return_value, and `side_effect` are keyword-only arguments.

  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)

    子のモックを作成し、その値を返すようにしてください。デフォルトでは親と同じタイプで作成されます。サブクラスで子モックの作成される方法をカスタマイズしたい場合には、このメソッドをオーバーライドします。

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

  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

    This is either `None` (if the mock hasn't been called), or the arguments that the mock was last called with. This will be in the form of a tuple: the first member, which can also be accessed through the `args` property, is any ordered arguments the mock was called with (or an empty tuple) and the second member, which can also be accessed through the `kwargs` property, is any keyword arguments (or an empty dictionary).

        >>> 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 を参照してください。

    注釈

    The way `mock_calls` are recorded means that where nested calls are made, the parameters of ancestor calls are not recorded and so will always compare equal:

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

  __class__

    通常、オブジェクトの `__class__` 属性はその型を返します。 `spec` を設定したオブジェクトの場合、 `__class__` は代わりに `spec` のクラスを返します。これにより、置き換え / 偽装しているオブジェクトに対する `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()` and `assert_any_call()` にも適用されます。 autospec を使う と、 モックオブジェクトのメソッド呼び出しにも適用されます。

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

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

  A mock intended to be used as a `property`, or other descriptor, on a class. `PropertyMock` provides `__get__()` and `__set__()` methods so you can specify a return value when it is fetched.

  オブジェクトから `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()

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

  An asynchronous version of `MagicMock`. The `AsyncMock` object will behave so the object is recognized as an async function, and the result of a call is an awaitable.

      >>> mock = AsyncMock()
      >>> asyncio.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:

  - if `side_effect` is a function, the async function will return the result of that function,

  - if `side_effect` is an exception, the async function will raise the exception,

  - if `side_effect` is an iterable, the async function will return the next value of the iterable, however, if the sequence of result is exhausted, `StopAsyncIteration` is raised immediately,

  - if `side_effect` is not defined, the async function will return the value defined by `return_value`, hence, by default, the async function returns a new `AsyncMock` object.

  Setting the spec of a `Mock` or `MagicMock` to an async function will result in a coroutine object being returned after calling.

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

  Setting the spec of a `Mock`, `MagicMock`, or `AsyncMock` to a class with asynchronous and synchronous functions will automatically detect the synchronous functions and set them as `MagicMock` (if the parent mock is `AsyncMock` or `MagicMock`) or `Mock` (if the parent mock is `Mock`). All asynchronous functions will be `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='...'>

  バージョン 3.8 で追加.

  assert_awaited()

    Assert that the mock was awaited at least once. Note that this is separate from the object having been called, the `await` keyword must be used:

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

    Assert that the mock was awaited exactly once.

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

  assert_awaited_with(*args, **kwargs)

    Assert that the last await was with the specified arguments.

        >>> mock = AsyncMock()
        >>> 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 call not found.
        Expected: mock('other')
        Actual: mock('foo', bar='bar')

  assert_awaited_once_with(*args, **kwargs)

    Assert that the mock was awaited exactly once and with the specified arguments.

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

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

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

    Assert the mock has been awaited with the specified calls. The `await_args_list` list is checked for the awaits.

    If any_order is false then the awaits must be sequential. There can be extra calls before or after the specified awaits.

    If any_order is true then the awaits can be in any order, but they must all appear in `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()

    Assert that the mock was never awaited.

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

  reset_mock(*args, **kwargs)

    See `Mock.reset_mock()`. Also sets `await_count` to 0, `await_args` to None, and clears the `await_args_list`.

  await_count

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

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

  await_args

    This is either `None` (if the mock hasn’t been awaited), or the arguments that the mock was last awaited with. Functions the same as `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

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

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

### 呼び出し

モックオブジェクトは呼び出し可能です。呼び出しの戻り値は `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` の内部で `mock.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]

例外は特殊メソッドと属性だけです (これらは2つのアンダースコアで開始・終了します)。モックはこれらの代わりに `AttributeError` を発生させます。これは、インタープリタが暗黙的にこれらのメソッドを要求するためであり、特殊メソッドを予測する際に 非常に 混乱してしまいます。もし特殊メソッドのサポートが必要な場合は、 magic methods を参照してください。

## patcher

patch デコレータは、その関数のスコープ内でパッチを適用するオブジェクトに対して使用されます。たとえ例外が発生したとしても、パッチは自動的に解除されます。これらすべての機能は文やクラスのデコレータとしても使用できます。

### 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 文が終了すると、パッチは元に戻されます。

  If new is omitted, then the target is replaced with an `AsyncMock` if the patched object is an async function or a `MagicMock` otherwise. If `patch()` is used as a decorator and new is omitted, the created mock is passed in as an extra argument to the decorated function. If `patch()` is used as a context manager the created mock is returned by the context manager.

  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 allows you to specify a different class, or callable object, that will be called to create the new object. By default `AsyncMock` is used for async functions and `MagicMock` for the rest.

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

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

  By default `patch()` will fail to replace attributes that don't exist. If you pass in `create=True`, and the attribute doesn't exist, patch will create the attribute for you when the patched function is called, and delete it again after the patched function has exited. This is useful for writing tests against attributes that your production code creates at runtime. It is off by default because it can be dangerous. With it switched on you can write passing tests against APIs that don't actually exist!

  注釈

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

  patch は `TestCase` のクラスデコレータとして利用できます。この場合そのクラスの各テストメソッドをデコレートします。これによりテストメソッドが同じ patch を共有している場合に退屈なコードを減らすことができます。 `patch()` は `patch.TEST_PREFIX` で始まるメソッド名のメソッドを探します。デフォルトではこれは `'test'` で、 `unittest` がテストを探す方法とマッチしています。 `patch.TEST_PREFIX` を設定することで異なる prefix を指定することもできます。

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

  `patch()` takes arbitrary keyword arguments. These will be passed to `AsyncMock` if the patched object is asynchronous, to `MagicMock` otherwise or to new_callable if specified.

  異なるユースケースのために、 `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

By default, attempting to patch a function in a module (or a method or an attribute in a class) that does not exist will fail with `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'

but adding `create=True` in the call to `patch()` will make the previous example work as expected:

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

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

### 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()` now returns the patched dictionary when used as a context manager.

`patch.dict()` can be used as a context manager, decorator or class decorator:

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

When used as a class decorator `patch.dict()` honours `patch.TEST_PREFIX` (default to `'test'`) for choosing which methods to wrap:

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

If you want to use a different prefix for your test, you can inform the patchers of the different prefix by setting `patch.TEST_PREFIX`. For more details about how to change the value of see 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

すべての patcher は `start()` と `stop()` メソッドを持ちます。これを使うと、 with 文やデコレータをネストさせずに、 `setUp` メソッドで複数のパッチをシンプルに適用させることができます。

これらのメソッドを使うには、 `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
        -> Defines SomeClass

    b.py
        -> from a import SomeClass
        -> some_function instantiates SomeClass

いま、 `some_function` をテストしようとしていて、そのために `SomeClass` を `patch()` を使って mock しようとしています。 モジュール b をインポートした時点で、 b は `SomeClass` を a からインポートしています。この状態で `a.SomeClass` を `patch()` を使って mock out してもテストには影響しません。モジュール 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` supports mocking the Python protocol methods, also known as "magic methods". This allows mock objects to replace containers or other objects that implement Python protocols.

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

- Context manager: `__enter__`, `__exit__`, `__aenter__` and `__aexit__`

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

- The numeric methods (including right hand and in-place variants): `__add__`, `__sub__`, `__mul__`, `__matmul__`, `__truediv__`, `__floordiv__`, `__mod__`, `__divmod__`, `__lshift__`, `__rshift__`, `__and__`, `__xor__`, `__or__`, and `__pow__`

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

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

- pickle: `__reduce__`, `__reduce_ex__`, `__getinitargs__`, `__getnewargs__`, `__getstate__`, `__setstate__`

- File system path representation: `__fspath__`

- Asynchronous iteration methods: `__aiter__` and `__anext__`

バージョン 3.8 で変更: Added support for `os.PathLike.__fspath__()`.

バージョン 3.8 で変更: Added support for `__aenter__`, `__aexit__`, `__aiter__` and `__anext__`.

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

- `__getattr__`, `__setattr__`, `__init__`, `__new__`

- `__prepare__`, `__instancecheck__`, `__subclasscheck__`, `__del__`

### Magic Mock

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

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

  `MagicMock` is a subclass of `Mock` with default implementations of most of the magic methods. You can use `MagicMock` without having to configure the magic methods yourself.

  コンストラクタの引数は `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

The two equality methods, `__eq__()` and `__ne__()`, are special. They do the default equality comparison on identity, using the `side_effect` attribute, unless you change their return value to return something else:

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

`MagicMock.__iter__()` の return_value は任意の iterable で、イテレータである必要はありません:

    >>> 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` はいくつかの曖昧であったり時代遅れなものをのぞいて、対応している magic method を事前にセットアップします。自動でセットアップされていないものも必要なら手動でセットアップすることができます。

`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 で変更: The `sentinel` attributes now preserve their identity when they are `copied` or `pickled`.

特定のオブジェクトが他のメソッドに引数として渡されることをテストしたり、返されることをテストしたい場合があります。このテストのために名前がついた 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)

`mock_calls` などの call list との比較に `ANY` を使うこともできます:

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

`ANY` is not limited to comparisons with call objects and so can also be used in test assertions:

    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__',
     ...

Alternatively you can just use `vars(my_mock)` (instance members) and `dir(type(my_mock))` (type members) to bypass the filtering irrespective of `mock.FILTER_DIR`.

### mock_open

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

  `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 で変更: Added `__iter__()` to implementation so that iteration (such as in for loops) correctly consumes read_data.

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

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

The issue is that even if you mock out the call to `open()` it is the returned object that is used as a context manager (and has `__enter__()` and `__exit__()` called).

コンテキストマネージャーを `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 は mock の `spec` 機能を基盤にしています。 autospec は mock の API を元のオブジェクト (spec) に制限しますが、再帰的に適用される (lazy に実装されている) ので、 mock の属性も spec の属性と同じ API だけを持つようになります。さらに、 mock された関数/メソッドは元と同じシグネチャを持ち、正しくない引数で呼び出されると `TypeError` を発生させます。

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

`Mock` is a very powerful and flexible object, but it suffers from two flaws when used to mock out objects from a system under test. One of these flaws is specific to the `Mock` api and the other is a more general problem with using mock objects.

First the problem specific to `Mock`. `Mock` has two assert methods that are extremely handy: `assert_called_with()` and `assert_called_once_with()`.

    >>> mock = Mock(name='Thing', return_value=None)
    >>> mock(1, 2, 3)
    >>> mock.assert_called_once_with(1, 2, 3)
    >>> mock(1, 2, 3)
    >>> mock.assert_called_once_with(1, 2, 3)
    Traceback (most recent call last):
     ...
    AssertionError: Expected 'mock' to be called once. Called 2 times.

Because mocks auto-create attributes on demand, and allow you to call them with arbitrary arguments, if you misspell one of these assert methods then your assertion is gone:

    >>> mock = Mock(name='Thing', return_value=None)
    >>> mock(1, 2, 3)
    >>> mock.assret_called_once_with(4, 5, 6)  # Intentional typo!

Your tests can pass silently and incorrectly because of the typo.

The second issue is more general to mocking. If you refactor some of your code, rename members and so on, any tests for code that is still using the old api but uses mocks instead of the real objects will still pass. This means your tests can all pass even though your code is broken.

各ユニットが互いにどのように接続されるかをテストしない場合、依然としてテストで見つけることができるバグの余地が多く残っています。

`mock` はこの問題に対処するために spec と呼ばれる機能を提供しています。何かクラスかインスタンスを `spec` として mock に渡すと、実際のクラスに存在する属性にしか、 mock に対してもアクセスできなくなります:

    >>> 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.has_data()
    <mock.Mock object at 0x...>
    >>> mock.has_data.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つの引数を持っています (片方は 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` オブジェクトは callable ではないので、 `request.Request` の mock から返されたインスタンスの mock は callable ではなくなります。 spec があれば、 assert のミススペルは正しいエラーを発生させます:

    >>> req.add_header('spam', 'eggs')
    <MagicMock name='request.Request().add_header()' id='...'>
    >>> req.add_header.assret_called_with  # Intentional typo!
    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='...'>

とはいえ、autospec には注意しなければならない点や制限があり、そのためデフォルトでは無効になっています。spec オブジェクトでどんな属性が使えるかどうかを調べるために、autospec は spec オブジェクトをイントロスペクト (実際に属性にアクセスする) 必要があります。mock の属性を利用するとき、水面下で元のオブジェクトに対しても同じ属性の探索が行われます。spec したオブジェクトのどれかがコードを実行するプロパティやデスクリプタを持っている場合、autospec は正しく動きません。もしくは、イントロスペクションしても安全なようにオブジェクトを設計するのがよいでしょう [4]。

A more serious problem is that it is common for instance attributes to be created in the `__init__()` method and not to exist on the class at all. autospec can't know about any dynamically created attributes and restricts the api to visible attributes.

    >>> 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 は属性を参照することを禁止しますが、設定することは禁止していません:

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

Probably the best way of solving the problem is to add class attributes as default values for instance members initialised in `__init__()`. Note that if you are only setting default attributes in `__init__()` then providing them via class attributes (shared between instances of course) is faster too. e.g.

    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()` を呼び出して - 検索するだけです。

### Sealing mocks

unittest.mock.seal(mock)

  Seal will disable the automatic creation of mocks when accessing an attribute of the mock being sealed or any of its attributes that are already mocks recursively.

  If a mock instance with a name or a spec is assigned to an attribute it won't be considered in the sealing chain. This allows one to prevent seal from fixing part of the mock object.

      >>> mock = Mock()
      >>> mock.submock.attribute1 = 2
      >>> mock.not_submock = mock.Mock(name="sample_name")
      >>> seal(mock)
      >>> mock.new_attribute  # This will raise AttributeError.
      >>> mock.submock.attribute2  # This will raise AttributeError.
      >>> mock.not_submock.attribute2  # This won't raise.

  バージョン 3.7 で追加.

## Order of precedence of `side_effect`, `return_value` and wraps

The order of their precedence is:

1. `side_effect`

2. `return_value`

3. wraps

If all three are set, mock will return the value from `side_effect`, ignoring `return_value` and the wrapped object altogether. If any two are set, the one with the higher precedence will return the value. Regardless of the order of which was set first, the order of precedence remains unchanged.

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

As `None` is the default value of `side_effect`, if you reassign its value back to `None`, the order of precedence will be checked between `return_value` and the wrapped object, ignoring `side_effect`.

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

If the value being returned by `side_effect` is `DEFAULT`, it is ignored and the order of precedence moves to the successor to obtain the value to return.

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

When `Mock` wraps an object, the default value of `return_value` will be `DEFAULT`.

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

The order of precedence will ignore this value and it will move to the last successor which is the wrapped object.

As the real call is being made to the wrapped object, creating an instance of this mock will return the real instance of the class. The positional arguments, if any, required by the wrapped object must be passed.

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

But if you assign `None` to it, this will not be ignored as it is an explicit assignment. So, the order of precedence will not move to the wrapped object.

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

Even if you set all three at once when initializing the mock, the order of precedence remains the same:

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

If `side_effect` is exhausted, the order of precedence will not cause a value to be obtained from the successors. Instead, `StopIteration` exception is raised.

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