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

Added in version 3.3.

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

======================================================================

"unittest.mock" is a library for testing in Python. It allows you to
replace parts of your system under test with mock objects and make
assertions about how they have been used.

"unittest.mock" provides a core "Mock" class removing the need to
create a host of stubs throughout your test suite. After performing an
action, you can make assertions about which methods / attributes were
used and arguments they were called with. You can also specify return
values and set needed attributes in the normal way.

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

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

     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)

      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.
      Calls: [call('foo', bar='baz'), call('other', bar='values')].

   assert_any_call(*args, **kwargs)

      assert the mock has been called with the specified arguments.

      The assert passes if the mock 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)

      assert the mock has been called with the specified calls. The
      "mock_calls" list is checked for the 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

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

      *return_value* parameter when set to "True" resets
      "return_value":

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

      *side_effect* parameter when set to "True" resets "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='...'>

      Note that "reset_mock()" *doesn't* clear the "return_value",
      "side_effect" or any child attributes you have set using normal
      assignment by default.

      Child mocks are reset as well.

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

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

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

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

   "property" もしくは:term:*デスクリプタ <descriptor>* として使われる
   ためのモックです。 "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()

注意:

  If an "AttributeError" is raised by "PropertyMock", it will be
  interpreted as a missing descriptor and "__getattr__()" will be
  called on the parent mock:

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

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

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

   Added in version 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.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 await not found.
      Expected: mock('other')
      Actual: mock('foo', bar='bar')

   assert_awaited_once_with(*args, **kwargs)

      Assert that the mock was awaited exactly once and with the
      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')]

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

   A version of "MagicMock" for multithreading tests. The
   "ThreadingMock" object provides extra methods to wait for a call to
   be invoked, rather than assert on it immediately.

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

   You can configure the global default timeout by setting
   "ThreadingMock.DEFAULT_TIMEOUT".

   wait_until_called(*, timeout=UNSET)

      Waits until the mock is called.

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

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

   wait_until_any_call_with(*args, **kwargs)

      Waits until the mock is called with the specified arguments.

      If a timeout was passed at the creation of the mock the function
      raises an "AssertionError" if the call is not performed in time.

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

   DEFAULT_TIMEOUT

      Global default timeout in seconds to create instances of
      "ThreadingMock".

   Added in version 3.13.


呼び出し
--------

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

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

If "side_effect" is set then it will be called after the call has been
recorded, so if "side_effect" raises an exception the call is still
recorded.

呼び出された際に例外を発生させるモックを作成するためには、
"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')]

If "side_effect" is a function then whatever that function returns is
what calls to the mock return. The "side_effect" function is called
with the same arguments as the mock. This allows you to vary the
return value of the call dynamically, based on the input:

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

If you want the mock to still return the default return value (a new
mock), or any set return value, then there are two ways of doing this.
Either return "return_value" from inside "side_effect", or return
"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

To remove a "side_effect", and return to the default behaviour, set
the "side_effect" to "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

The "side_effect" can also be any iterable object. Repeated calls to
the mock will return values from the iterable (until the iterable is
exhausted and a "StopIteration" is raised):

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


属性の削除
----------

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

You may want a mock object to return "False" to a "hasattr()" call, or
raise an "AttributeError" when an attribute is fetched. You can do
this by providing an object as a "spec" for a mock, but that isn't
always convenient.

属性を削除することで， "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 can be used as a "TestCase" class decorator. It works by
   decorating each test method in the class. This reduces the
   boilerplate code when your test methods share a common patchings
   set. "patch()" finds tests by looking for method names that start
   with "patch.TEST_PREFIX". By default this is "'test'", which
   matches the way "unittest" finds tests. You can specify an
   alternative prefix by setting "patch.TEST_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* に、何でも
好きなものを設定できます。

To configure return values on methods of *instances* on the patched
class you must do this on the "return_value". For example:

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

   Patch a dictionary, or dictionary like object, and restore the
   dictionary to its original state after the test, where the restored
   dictionary is a copy of the dictionary as it was before the test.

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

All the patchers have "start()" and "stop()" methods. These make it
simpler to do patching in "setUp" methods or where you want to do
multiple patches without nesting decorators or with statements.

To use them call "patch()", "patch.object()" or "patch.dict()" as
normal and keep a reference to the returned "patcher" object. You can
then call "start()" to put the patch in place and "stop()" to undo it.

"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

A typical use case for this might be for doing multiple patches in the
"setUp" method of a "TestCase":

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

Now we want to test "some_function" but we want to mock out
"SomeClass" using "patch()". The problem is that when we import module
b, which we will have to do when it imports "SomeClass" from module a.
If we use "patch()" to mock out "a.SomeClass" then it will have no
effect on our test; module b already has a reference to the *real*
"SomeClass" and it looks like our patching had no effect.

重要なのは、 "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

The return value of "__iter__()" can be any iterable object and isn't
required to be an iterator:

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


mock_open
---------

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

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

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

   *read_data* is a string for the "read()", "readline()", and
   "readlines()" methods of the file handle to return.  Calls to those
   methods will take data from *read_data* until it is depleted.  The
   mock of these methods is pretty simplistic: every time the *mock*
   is called, the *read_data* is rewound to the start.  If you need
   more control over the data that you are feeding to the tested code
   you will need to customize this mock for yourself.  When that is
   insufficient, one of the in-memory filesystem packages on PyPI can
   offer a realistic filesystem for testing.

   バージョン 3.4 で変更: Added "readline()" and "readlines()"
   support. The mock of "read()" changed to consume *read_data* rather
   than returning it on each call.

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

Autospeccing is based on the existing "spec" feature of mock. It
limits the api of mocks to the api of an original object (the spec),
but it is recursive (implemented lazily) so that attributes of mocks
only have the same api as the attributes of the spec. In addition
mocked functions / methods have the same call signature as the
original so they raise a "TypeError" if they are called incorrectly.

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

"Mock" is a very powerful and flexible object, but it suffers from a
flaw which is 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.

バージョン 3.5 で変更: Before 3.5, tests with a typo in the word
assert would silently pass when they should raise an error. You can
still achieve this behavior by passing "unsafe=True" to Mock.

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

"unittest.mock" already provides a feature to help with this, called
speccing. If you use a class or instance as the "spec" for a mock then
you can only access attributes on the mock that exist on the real
class:

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

You can see that "request.Request" has a spec. "request.Request" takes
two arguments in the constructor (one of which is *self*). Here's what
happens if we try to call it incorrectly:

   >>> 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" objects are not callable, so the return value of
instantiating our mocked out "request.Request" is a non-callable mock.
With the spec in place any typos in our asserts will raise the correct
error:

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

   Added in version 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
