راهنمای سریع¶

اشیای 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() می‌تواند به‌عنوان مدیر زمینه در یک دستور 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 از ماک کردن متدهای جادویی پایتون پشتیبانی می‌کند. ساده‌ترین راه برای استفاده از متدهای ویژه، استفاده از کلاس MagicMock است. این کلاس به شما امکان می‌دهد کارهایی مانند موارد زیر را انجام دهید:

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

ماک به شما اجازه می‌دهد توابع (یا دیگر نمونه‌های ماک) را به متدهای جادویی اختصاص دهید و آن‌ها به‌درستی فراخوانی می‌شوند. کلاس MagicMock صرفاً گونه‌ای از ماک است که تمام متدهای ویژه آن از پیش برای شما ایجاد شده‌اند (البته به‌هرحال همه‌ی متدهای مفید).

در زیر مثالی از استفاده از متدهای جادویی با کلاس معمولی Mock آمده است:

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

برای اطمینان از اینکه اشیای ماک در آزمون‌های شما همان API اشیایی را دارند که جایگزین آن‌ها می‌شوند، می‌توانید از auto-speccing استفاده کنید. Auto-speccing را می‌توان از طریق آرگومان autospec در patch، یا تابع create_autospec() انجام داد. 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 یک شیء ماک انعطاف‌پذیر است که برای جایگزینی استفاده از جایگزین‌های موقت (stubs) و جایگزین‌های آزمون (test doubles) در سراسر کد شما در نظر گرفته شده است. ماک‌ها فراخوانی‌پذیر هستند و هنگامی که به ویژگی‌های آن‌ها دسترسی پیدا می‌کنید، آن ویژگی‌ها را به‌عنوان ماک‌های جدید ایجاد می‌کنند [1]. دسترسی به همان ویژگی همیشه همان ماک را برمی‌گرداند. ماک‌ها نحوه استفاده شما از آن‌ها را ثبت می‌کنند و به شما امکان می‌دهند درباره آنچه کد شما با آن‌ها انجام داده است، ادعاهایی مطرح کنید.

MagicMock یک زیرکلاس از Mock است که تمام متدهای جادویی آن از پیش ساخته‌شده‌اند و آماده استفاده هستند. همچنین گونه‌های غیرفراخوانی‌پذیر نیز وجود دارند که هنگام ماک‌کردن اشیایی که فراخوانی‌پذیر نیستند، مفید هستند: NonCallableMock و NonCallableMagicMock

دکوراتورهای patch() جایگزینی موقت کلاس‌ها در یک ماژول خاص با یک شیء Mock را آسان می‌کنند. به‌طور پیش‌فرض، patch() یک MagicMock برای شما ایجاد می‌کند. شما می‌توانید با استفاده از آرگومان new_callable در patch()، یک کلاس جایگزین برای 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 چند آرگومان اختیاری می‌گیرد که رفتار شیء Mock را مشخص می‌کنند:

• spec: این می‌تواند یک فهرست از رشته‌ها یا یک شیء موجود (یک کلاس یا نمونه) باشد که به‌عنوان مشخصات برای شیء ماک عمل می‌کند. اگر یک شیء را به‌عنوان ورودی بدهید، یک فهرست از رشته‌ها با فراخوانی dir روی آن شیء تشکیل می‌شود (به‌جز ویژگی‌ها و متدهای ویژه پشتیبانی‌نشده). دسترسی به هر ویژگی که در این فهرست نباشد، باعث پرتاب AttributeError می‌شود.

  اگر spec یک شیء باشد (نه فهرستی از رشته‌ها)، آنگاه __class__ کلاس شیء spec را برمی‌گرداند. این به ماک‌ها اجازه می‌دهد آزمون‌های isinstance() را بگذرانند.

• spec_set: گونه‌ای سخت‌گیرانه‌تر از spec. در صورت استفاده، تلاش برای set کردن یا دریافت یک ویژگی روی ماک که آن ویژگی روی شیء ارسال‌شده به‌عنوان spec_set وجود ندارد، باعث پرتاب AttributeError می‌شود.

• side_effect: تابعی که هرگاه ماک فراخوانی شود، فراخوانی می‌شود. ویژگی side_effect را ببینید. برای پرتاب استثناها یا تغییر مقادیر بازگشتی به‌صورت پویا مفید است. این تابع با همان آرگومان‌های ماک فراخوانی می‌شود، و مگر اینکه DEFAULT را برگرداند، مقدار بازگشتی این تابع به‌عنوان مقدار بازگشتی استفاده می‌شود.

  به‌عنوان جایگزین، side_effect می‌تواند یک کلاس یا نمونه استثنا باشد. در این صورت، هنگام فراخوانی ماک، استثنا پرتاب می‌شود.

  اگر side_effect یک پیمایش‌پذیر باشد، هر فراخوانی ماک مقدار بعدی را از آن پیمایش‌پذیر برمی‌گرداند.

  می‌توان یک side_effect را با تنظیم آن به None پاک کرد.

• return_value: مقداری که هنگام فراخوانی ماک برگردانده می‌شود. به‌طور پیش‌فرض، این یک Mock جدید است (که در اولین دسترسی ایجاد می‌شود). ویژگی return_value را ببینید.

• unsafe: به‌طور پیش‌فرض، دسترسی به هر ویژگی که نام آن با assert، assret، asert، aseert یا assrt آغاز می‌شود، باعث پرتاب استثنای AttributeError می‌شود. ارسال unsafe=True دسترسی به این ویژگی‌ها را مجاز می‌کند.

  اضافه شده در نسخه‌ی 3.5.

• wraps: آیتمی که شیء ماک باید آن را پوشش دهد. اگر wraps برابر None نباشد، فراخوانی Mock فراخوانی را به شیء پوشش‌داده‌شده منتقل می‌کند (نتیجه واقعی را برمی‌گرداند). دسترسی به ویژگی روی ماک، یک شیء 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.
Calls: [call(), call()].

اضافه شده در نسخه‌ی 3.6.

assert_called_with(*args, **kwargs)¶

این متد روش مناسبی برای تأیید این است که آخرین فراخوانی به‌شکل خاصی انجام شده است:

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

assert_called_once_with(*args, **kwargs)¶

تأیید کنید که ماک دقیقاً یک بار فراخوانی شده است و آن فراخوانی با آرگومان‌های مشخص‌شده بوده است.

>>> mock = Mock(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) در صورتی موفق می‌شود که ماک تاکنون فراخوانی شده باشد، برخلاف assert_called_with() و assert_called_once_with() که فقط در صورتی موفق می‌شوند که فراخوانی، آخرین فراخوانی باشد، و در مورد assert_called_once_with() باید تنها فراخوانی نیز باشد.

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

assert_has_calls(calls, any_order=False)¶

بررسی کنید که ماک با فراخوانی‌های مشخص‌شده فراخوانی شده است. فهرست mock_calls برای این فراخوانی‌ها بررسی می‌شود.

اگر any_order نادرست باشد، فراخوانی‌ها باید متوالی باشند. ممکن است فراخوانی‌های اضافی قبل یا بعد از فراخوانی‌های مشخص‌شده وجود داشته باشد.

اگر any_order درست باشد، فراخوانی‌ها می‌توانند به هر ترتیبی باشند، اما همه باید در 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()].

اضافه شده در نسخه‌ی 3.5.

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

متد reset_mock تمام ویژگی‌های فراخوانی یک شیء ماک را بازنشانی می‌کند:

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

این می‌تواند در مواردی مفید باشد که می‌خواهید مجموعه‌ای از ادعاها را که از همان شیء استفاده‌ی مجدد می‌کنند، مطرح کنید.

پارامتر return_value وقتی روی True تنظیم شود، return_value را بازنشانی می‌کند:

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

پارامتر side_effect هنگامی که روی True تنظیم شود، side_effect را بازنشانی می‌کند:

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

توجه داشته باشید که reset_mock() به‌طور پیش‌فرض return_value، side_effect یا هیچ‌کدام از ویژگی‌های فرزند را که با انتساب معمولی تنظیم کرده‌اید، پاک نمی‌کند.

ماک‌های فرزند نیز بازنشانی می‌شوند.

تغییر یافته در نسخه‌ی 3.6: دو آرگومان فقط‌کلیدواژه‌ای به تابع reset_mock افزوده شد.

mock_add_spec(spec, spec_set=False)¶

مشخصات را به یک ماک اضافه کنید. spec می‌تواند یک شیء یا فهرستی از رشته‌ها باشد. فقط ویژگی‌های موجود در spec را می‌توان به‌عنوان ویژگی از ماک واکشی کرد.

اگر spec_set درست باشد، تنها ویژگی‌های موجود در spec قابل تنظیم هستند.

attach_mock(mock, attribute)¶

یک ماک را به‌عنوان ویژگی این ماک متصل کنید و نام و والد آن را جایگزین نمایید. فراخوانی‌های ماک متصل‌شده در ویژگی‌های method_calls و mock_calls این ماک ثبت خواهند شد.

configure_mock(**kwargs)¶

ویژگی‌های ماک را از طریق آرگومان‌های کلیدواژه‌ای تنظیم کنید.

می‌توان ویژگی‌ها به‌همراه مقادیر بازگشتی و عوارض جانبی را روی ماک‌های فرزند با استفاده از نماد نقطه‌ای استاندارد و واگشایی یک دیکشنری در فراخوانی متد تنظیم کرد:

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

همین مورد را می‌توان در فراخوانی سازنده‌ی ماک‌ها به دست آورد:

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

configure_mock() برای آسان‌تر کردن انجام پیکربندی پس از ایجاد ماک وجود دارد.

__dir__()¶

اشیای Mock نتایج dir(some_mock) را به نتایج مفید محدود می‌کنند. برای ماک‌های دارای spec، این شامل تمام ویژگی‌های مجاز برای ماک می‌شود.

برای آگاهی از عملکرد این پالایش و چگونگی غیرفعال کردن آن، FILTER_DIR را ببینید.

_get_child_mock(**kw)¶

ماک‌های فرزند را برای ویژگی‌ها و مقدار بازگشتی ایجاد می‌کند. به‌طور پیش‌فرض، ماک‌های فرزند از همان نوع والد خواهند بود. زیرکلاس‌های Mock ممکن است بخواهند این را بازنویسی کنند تا نحوه‌ی ساخت ماک‌های فرزند را سفارشی‌سازی کنند.

برای ماک‌های غیرفراخوانی‌پذیر، از نوع فراخوانی‌پذیر استفاده خواهد شد (به‌جای هر زیرکلاس سفارشی).

called¶

یک بولی که نشان می‌دهد شیء ماک فراخوانی شده است یا خیر:

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

call_count¶

عدد صحیحی که به شما می‌گوید شیء ماک چند بار فراخوانی شده است:

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

return_value¶

این را تنظیم کنید تا مقدار برگردانده‌شده با فراخوانی ماک پیکربندی شود:

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

مقدار بازگشتی پیش‌فرض یک شیء ماک است و شما می‌توانید آن را به روش معمول پیکربندی کنید:

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

return_value را نیز می‌توان در سازنده تنظیم کرد:

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

side_effect¶

این می‌تواند یک تابع برای فراخوانی هنگام فراخوانی ماک، یک پیمایش‌پذیر، یا یک استثنا (کلاس یا نمونه) برای پرتاب باشد.

اگر تابعی را به‌عنوان ورودی بدهید، آن تابع با همان آرگومان‌هایی که ماک دریافت می‌کند فراخوانی می‌شود و مگر آنکه تابع شیء یکتای DEFAULT را برگرداند، فراخوانی ماک هر مقداری را که تابع برگرداند برمی‌گرداند. اگر تابع DEFAULT را برگرداند، آنگاه ماک مقدار معمول خود را (از return_value) برمی‌گرداند.

اگر یک پیمایش‌پذیر به آن بدهید، از آن برای گرفتن یک پیمایش‌گر استفاده می‌شود که باید در هر فراخوانی یک مقدار تولید کند. این مقدار می‌تواند یک نمونه استثنا باشد که پرتاب می‌شود، یا مقداری که از فراخوانی ماک بازگردانده می‌شود (مدیریت 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 را می‌توان در سازنده تنظیم کرد. در اینجا مثالی آمده است که یک واحد به مقداری که ماک با آن فراخوانی می‌شود می‌افزاید و آن را برمی‌گرداند:

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

تنظیم side_effect روی None آن را پاک می‌کند:

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

call_args¶

این مقدار یا None است (اگر ماک فراخوانی‌نشده باشد)، یا آرگومان‌هایی که ماک آخرین بار با آن‌ها فراخوانی شده است. این مقدار در قالب یک تاپل خواهد بود: عضو اول، که می‌توان از طریق ویژگی args نیز به آن دسترسی داشت، آرگومان‌های جایگاهی است که ماک با آن‌ها فراخوانی شده است (یا یک تاپل خالی) و عضو دوم، که می‌توان از طریق ویژگی kwargs نیز به آن دسترسی داشت، آرگومان‌های کلیدواژه‌ای است (یا یک دیکشنری خالی).

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

call_args، به‌همراه اعضای فهرست‌های call_args_list، method_calls و mock_calls، اشیای call هستند. این‌ها تاپل هستند، بنابراین می‌توان آن‌ها را واگشایی کرد تا به آرگومان‌های جداگانه دسترسی پیدا کرد و ادعاهای پیچیده‌تری مطرح کرد. به فراخوانی‌ها به‌عنوان تاپل مراجعه کنید.

تغییر یافته در نسخه‌ی 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 هستند. می‌توانید آن‌ها را به‌صورت تاپل واگشایی کنید تا به آرگومان‌های منفرد دسترسی پیدا کنید. به فراخوانی‌ها به‌صورت تاپل مراجعه کنید.

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 هستند. می‌توان آن‌ها را به‌صورت تاپل واگشایی کرد تا به آرگومان‌های جداگانه دسترسی پیدا کرد. فراخوانی‌ها به‌صورت تاپل را ببینید.

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 هستند. می‌توانید این‌ها را به‌صورت تاپل واگشایی کنید تا به تک‌تک آرگومان‌ها دسترسی پیدا کنید. فراخوانی‌ها به‌صورت تاپل را ببینید.

نکته

نحوه‌ی ثبت mock_calls به این معناست که هرگاه فراخوانی‌های تودرتو انجام شوند، پارامترهای فراخوانی‌های بالادستی ثبت نمی‌شوند و بنابراین همیشه در مقایسه برابر خواهند بود:

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

__class__¶

معمولاً ویژگی __class__ یک شیء، نوع آن را برمی‌گرداند. برای یک شیء ماک دارای spec، ویژگی __class__ در عوض کلاس مشخص‌شده در spec را برمی‌گرداند. این امکان را به اشیاء ماک می‌دهد تا آزمون‌های isinstance() را برای شیءای که جایگزین آن هستند / خود را به‌جای آن جا می‌زنند، با موفقیت بگذرانند:

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

__class__ قابل انتساب است؛ این به یک ماک اجازه می‌دهد بدون اینکه شما را مجبور به استفاده از spec کند، بررسی isinstance() را بگذراند:

>>> 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 استفاده می‌کنند، می‌توانند آزمون‌های isinstance() را بگذرانند:

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

کلاس‌های Mock از ماک کردن متدهای جادویی پشتیبانی می‌کنند. برای جزئیات کامل، متدهای جادویی را ببینید.

کلاس‌های ماک و دکوراتورهای patch() همگی آرگومان‌های کلیدواژه‌ای دلخواه را برای پیکربندی می‌پذیرند. در دکوراتورهای patch()، کلیدواژه‌ها به سازنده‌ی ماکِ در حال ایجاد ارسال می‌شوند. آرگومان‌های کلیدواژه‌ای برای پیکربندی ویژگی‌های ماک هستند:

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

مقدار بازگشتی و اثر جانبی ماک‌های فرزند را می‌توان به همین روش، با استفاده از نمادگذاری نقطه‌ای تنظیم کرد. از آن‌جا که نمی‌توانید از نام‌های نقطه‌ای مستقیماً در یک فراخوانی استفاده کنید، باید یک دیکشنری ایجاد کنید و آن را با استفاده از ** واگشایی کنید:

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

یک ماک فراخوانی‌پذیر که با یک spec (یا یک spec_set) ایجاد شده است، هنگام تطبیق فراخوانی‌ها با ماک، امضای شیء مشخصات را درون‌نگری می‌کند. بنابراین، می‌تواند آرگومان‌های فراخوانی واقعی را صرف‌نظر از اینکه به‌صورت جایگاهی یا با نام ارسال شده باشند، تطبیق دهد:

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

این موضوع به assert_called_with()، assert_called_once_with()، assert_has_calls() و assert_any_call() اعمال می‌شود. هنگام مشخصه‌دهی خودکار (Autospeccing)، این موضوع در مورد فراخوانی‌های متد بر روی شیء ماک نیز اعمال می‌شود.

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

ماکی که برای استفاده به‌عنوان property، یا 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()

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

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

نسخه‌ای ناهمگام از MagicMock. شیء AsyncMock به‌گونه‌ای رفتار می‌کند که به‌عنوان یک تابع ناهمگام شناخته می‌شود، و نتیجه‌ی یک فراخوانی قابل await (awaitable) است.

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

نتیجه‌ی mock() یک تابع ناهمگام است که پس از این‌که await شد، نتیجه‌ی side_effect یا return_value را خواهد داشت:

• اگر side_effect یک تابع باشد، تابع ناهمگام نتیجه‌ی آن تابع را برمی‌گرداند،

• اگر side_effect یک استثنا باشد، تابع ناهمگام آن استثنا را پرتاب خواهد کرد،

• اگر side_effect یک پیمایش‌پذیر باشد، تابع ناهمگام مقدار بعدیِ پیمایش‌پذیر را برمی‌گرداند، با این حال، اگر دنباله‌ی نتیجه خالی‌شده باشد، StopAsyncIteration بلافاصله رخ می‌دهد،

• اگر side_effect تعریف‌نشده باشد، تابع ناهمگام مقدار تعریف‌شده توسط return_value را برمی‌گرداند، بنابراین، به‌طور پیش‌فرض، تابع ناهمگام یک شیء AsyncMock جدید برمی‌گرداند.

تنظیم spec یک Mock یا MagicMock روی یک تابع ناهمگام باعث می‌شود پس از فراخوانی، یک شیء هم‌روال برگردانده شود.

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

اگر spec یک Mock، MagicMock یا AsyncMock را روی کلاسی دارای توابع ناهمگام و همگام تنظیم کنید، توابع همگام به‌طور خودکار تشخیص داده می‌شوند و به‌صورت MagicMock (اگر ماک والد AsyncMock یا MagicMock باشد) یا Mock (اگر ماک والد Mock باشد) تنظیم می‌شوند. تمام توابع ناهمگام AsyncMock خواهند بود.

>>> class ExampleClass:
...     def sync_foo():
...         pass
...     async def async_foo():
...         pass
...
>>> a_mock = AsyncMock(ExampleClass)
>>> a_mock.sync_foo
<MagicMock name='mock.sync_foo' id='...'>
>>> a_mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>
>>> mock = Mock(ExampleClass)
>>> mock.sync_foo
<Mock name='mock.sync_foo' id='...'>
>>> mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>

اضافه شده در نسخه‌ی 3.8.

assert_awaited()¶

تأیید می‌کند که ماک حداقل یک بار await شده است. توجه داشته باشید که این از فراخوانی شدن شیء جدا است؛ باید از کلیدواژه await استفاده شود:

>>> mock = AsyncMock()
>>> async def main(coroutine_mock):
...     await coroutine_mock
...
>>> coroutine_mock = mock()
>>> mock.called
True
>>> mock.assert_awaited()
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited.
>>> asyncio.run(main(coroutine_mock))
>>> mock.assert_awaited()

assert_awaited_once()¶

ادعا کنید که ماک دقیقاً یک‌بار await شده است.

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

assert_awaited_with(*args, **kwargs)¶

تأیید می‌کند که آخرین await با آرگومان‌های مشخص‌شده انجام شده است.

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

assert_awaited_once_with(*args, **kwargs)¶

تصدیق می‌کند که ماک دقیقاً یک‌بار و با آرگومان‌های مشخص‌شده await شده است.

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

assert_any_await(*args, **kwargs)¶

ادعا می‌کند که ماک تاکنون با آرگومان‌های مشخص‌شده await شده است.

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

assert_has_awaits(calls, any_order=False)¶

تأیید می‌کند که ماک با فراخوانی‌های مشخص‌شده مورد await قرار گرفته است. فهرست await_args_list برای موارد await بررسی می‌شود.

اگر any_order نادرست باشد، awaitها باید به‌صورت متوالی انجام شوند. ممکن است فراخوانی‌های اضافی پیش یا پس از awaitهای مشخص‌شده وجود داشته باشند.

اگر any_order درست باشد، awaitها می‌توانند به هر ترتیبی باشند، اما همه‌ی آن‌ها باید در await_args_list ظاهر شوند.

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

assert_not_awaited()¶

تأیید می‌کند که ماک هرگز await نشده است.

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

reset_mock(*args, **kwargs)¶

Mock.reset_mock() را ببینید. همچنین await_count را برابر ۰، await_args را برابر None قرار می‌دهد و await_args_list را پاک می‌کند.

await_count¶

یک عدد صحیح که تعداد دفعات await شدن شیء ماک را پیگیری می‌کند.

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

await_args¶

این یا None است (اگر ماک await نشده باشد)، یا آرگومان‌هایی است که ماک آخرین بار با آن‌ها await شده است. مانند Mock.call_args عمل می‌کند.

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

await_args_list¶

این فهرستی از تمام موارد await انجام‌شده روی شیء ماک به‌ترتیب است (بنابراین طول فهرست برابر با تعداد دفعاتی است که آن شیء await شده است). پیش از انجام هرگونه await، این فهرست خالی است.

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

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

نسخه‌ای از MagicMock برای آزمون‌های چندنخی. شیء ThreadingMock متدهای اضافی‌ای فراهم می‌کند تا به‌جای ادعای فوری درباره‌ی یک فراخوانی، منتظر بمانید تا آن فراخوانی صورت گیرد.

مهلت پیش‌فرض توسط آرگومان timeout مشخص می‌شود، یا در صورت تنظیم‌نشدن، توسط ویژگی ThreadingMock.DEFAULT_TIMEOUT، که پیش‌فرض آن مسدودسازی (None) است.

می‌توانید با تنظیم ThreadingMock.DEFAULT_TIMEOUT، مهلت زمانی پیش‌فرض سراسری را پیکربندی کنید.

wait_until_called(*, timeout=UNSET)¶

صبر می‌کند تا ماک فراخوانی شود.

اگر در زمان ایجاد ماک یک مهلت زمانی پاس داده شده باشد یا یک آرگومان مهلت زمانی به این تابع پاس داده شود، در صورتی که فراخوانی به‌موقع انجام نشود، تابع استثنا AssertionError را پرتاب می‌کند.

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

wait_until_any_call_with(*args, **kwargs)¶

منتظر می‌ماند تا ماک با آرگومان‌های مشخص‌شده فراخوانی شود.

اگر در زمان ایجاد ماک، یک مهلت زمانی ارسال شده باشد، در صورتی که فراخوانی به‌موقع انجام نشود، تابع یک AssertionError پرتاب می‌کند.

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

DEFAULT_TIMEOUT¶

مهلت زمانی پیش‌فرض سراسری بر حسب ثانیه برای ایجاد نمونه‌های ThreadingMock.

اضافه شده در نسخه‌ی 3.13.

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

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

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

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

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

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

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

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

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

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

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

>>> thing1 = object()
>>> thing2 = object()
>>> parent = MagicMock()
>>> 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')]

وصله‌کننده‌ها¶

دکوراتورهای patch برای وصله کردن اشیاء فقط در محدوده تابعی که آن را دکور می‌کنند استفاده می‌شوند. آن‌ها به‌طور خودکار لغو وصله (unpatching) را برای شما مدیریت می‌کنند، حتی اگر استثناهایی پرتاب شوند. همچنین می‌توان از همه این توابع در دستورات with یا به‌عنوان دکوراتورهای کلاس استفاده کرد.

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

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

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

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

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

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

>>> config = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> patcher = patch('__main__.thing', **config)
>>> mock_thing = patcher.start()
>>> mock_thing.method()
3
>>> mock_thing.other()
Traceback (most recent call last):
  ...
KeyError

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

a.py
    -> Defines SomeClass

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

@patch('b.SomeClass')

@patch('a.SomeClass')

پشتیبانی از MagicMock و متدهای جادویی¶

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

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

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

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

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

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

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

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

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

کمک‌کننده‌ها¶

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