`test` --- بسته آزمون‌های رگرسیون برای پایتون¶

توجه

بسته‌ی test فقط برای استفاده‌ی داخلی توسط پایتون در نظر گرفته شده است. این بسته به‌منظور بهره‌مندی توسعه‌دهندگان اصلی پایتون مستند شده است. هرگونه استفاده از این بسته خارج از کتابخانه‌ی استاندارد پایتون توصیه نمی‌شود، زیرا کد ذکرشده در اینجا ممکن است بین نسخه‌های پایتون بدون اطلاع تغییر کند یا حذف شود.

بسته‌ی test شامل تمام آزمون‌های رگرسیون پایتون و همچنین ماژول‌های test.support و test.regrtest است. از test.support برای بهبود آزمون‌های شما استفاده می‌شود، در حالی که test.regrtest بدنه‌ی آزمون را راهبری می‌کند.

هر ماژول در بسته‌ی test که نام آن با test_ شروع می‌شود، یک بدنه‌ی آزمون برای یک ماژول یا قابلیت مشخص است. همه‌ی آزمون‌های جدید باید با استفاده از ماژول unittest یا doctest نوشته شوند. برخی آزمون‌های قدیمی‌تر با استفاده از شیوه‌ی آزمون‌نویسی «سنتی» نوشته شده‌اند که خروجی چاپ‌شده در sys.stdout را مقایسه می‌کند؛ این شیوه از آزمون، منسوخ محسوب می‌شود.

همچنین ملاحظه نمائید

ماژول unittest: نوشتن آزمون‌های رگرسیون PyUnit.
ماژول doctest: آزمون‌های نهفته در رشته مستندات.

نوشتن آزمون واحد‌ها برای بسته `test`¶

ترجیح داده می‌شود آزمون‌هایی که از ماژول unittest استفاده می‌کنند، چند دستورالعمل را رعایت کنند. یکی از این دستورالعمل‌ها این است که نام ماژول آزمون با test_ شروع شود و با نام ماژولی که آزمون می‌شود پایان یابد. متدهای آزمون در ماژول آزمون باید با test_ شروع شوند و با توصیفی از آنچه متد آزمون می‌کند پایان یابند. این کار لازم است تا راه‌انداز آزمون متدها را به‌عنوان متدهای آزمون شناسایی کند. همچنین نباید هیچ رشته‌ی مستندسازی برای متد درج شود. برای مستندسازی متدهای آزمون باید از یک کامنت (مانند # Tests function returns only True or False) استفاده شود. این کار به این دلیل انجام می‌شود که رشته مستندات در صورت وجود چاپ می‌شوند و بنابراین مشخص نمی‌شود چه آزمونی در حال اجرا است.

اغلب از یک کد پیش‌ساخته (boilerplate) ساده استفاده می‌شود:

import unittest
from test import support

class MyTestCase1(unittest.TestCase):

    # Only use setUp() and tearDown() if necessary

    def setUp(self):
        ... code to execute in preparation for tests ...

    def tearDown(self):
        ... code to execute to clean up after tests ...

    def test_feature_one(self):
        # Test feature one.
        ... testing code ...

    def test_feature_two(self):
        # Test feature two.
        ... testing code ...

    ... more test methods ...

class MyTestCase2(unittest.TestCase):
    ... same structure as MyTestCase1 ...

... more test classes ...

if __name__ == '__main__':
    unittest.main()

این الگوی کد اجازه می‌دهد بدنه‌ی آزمون توسط test.regrtest، به‌تنهایی به‌عنوان اسکریپتی که از رابط خط فرمان unittest پشتیبانی می‌کند، یا از طریق رابط خط فرمان python -m unittest اجرا شود.

هدف از آزمون رگرسیون این است که تلاش کنید کد را بشکنید. این امر به چند رهنمود منجر می‌شود که باید رعایت شوند:

بدنه‌ی آزمون باید همه کلاس‌ها، توابع و ثابت‌ها را آزمایش کند. این شامل نه‌تنها API خارجی‌ای است که به دنیای بیرون ارائه می‌شود، بلکه شامل کد «خصوصی» نیز می‌شود.
آزمون جعبه‌سفید (بررسی کدِ تحت آزمون هنگام نوشتن آزمون‌ها) ترجیح داده می‌شود. آزمون جعبه‌سیاه (آزمون تنها رابط کاربری منتشرشده) به اندازه کافی کامل نیست تا اطمینان حاصل شود که همه‌ی موارد مرزی و لبه‌ای آزمایش شده‌اند.
اطمینان حاصل کنید که همه‌ی مقادیر ممکن، از جمله مقادیر نامعتبر، آزمایش شده‌اند. این کار تضمین می‌کند که نه‌تنها همه‌ی مقادیر معتبر قابل‌قبول هستند، بلکه مقادیر نامناسب نیز به‌درستی مدیریت می‌شوند.
تا حد ممکن مسیرهای کد را پیمایش کنید. محل‌های وقوع شاخه‌بندی را آزمون کنید و بدین‌ترتیب ورودی را به‌گونه‌ای تنظیم کنید که اطمینان حاصل شود تا حد ممکن مسیرهای متفاوتی از کد طی می‌شود.
برای هر اشکالی که در کد آزمون‌شده کشف می‌شود، یک آزمون صریح اضافه کنید. این کار اطمینان می‌دهد که اگر کد در آینده تغییر کند، خطا دوباره ظاهر نمی‌شود.
حتماً پس از آزمون‌های خود پاک‌سازی کنید (مانند بستن و حذف همه‌ی پرونده‌های موقت).
اگر آزمونی به شرط خاصی از سیستم‌عامل وابسته است، پیش از اقدام به اجرای آزمون، تأیید کنید که آن شرط از قبل وجود دارد.
تا حد امکان ماژول‌های کمتری را ایمپورت کنید و این کار را در اسرع وقت انجام دهید. این کار هم وابستگی‌های خارجی آزمون‌ها و هم رفتار ناهنجار احتمالی ناشی از عوارض جانبی ایمپورت کردن یک ماژول را به حداقل می‌رساند.
سعی کنید بازاستفاده از کد را به حداکثر برسانید. گاهی ممکن است آزمون‌ها تنها به اندازه‌ی نوع ورودی استفاده‌شده متفاوت باشند. با ایجاد زیرکلاسی از یک کلاس آزمون پایه که ورودی را مشخص می‌کند، تکرار کد را به حداقل برسانید:
```
class TestFuncAcceptsSequencesMixin:

    func = mySuperWhammyFunction

    def test_func(self):
        self.func(self.arg)

class AcceptLists(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = [1, 2, 3]

class AcceptStrings(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = 'abc'

class AcceptTuples(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = (1, 2, 3)
```
هنگام استفاده از این الگو، به یاد داشته باشید که همه کلاس‌هایی که از unittest.TestCase ارث می‌برند، به‌عنوان آزمون اجرا می‌شوند. کلاس TestFuncAcceptsSequencesMixin در مثال بالا هیچ داده‌ای ندارد و بنابراین نمی‌تواند به‌تنهایی اجرا شود، از این رو از unittest.TestCase ارث نمی‌برد.

همچنین ملاحظه نمائید

توسعه آزمون‌محور: کتابی از کنت بک درباره‌ی نوشتن آزمون‌ها پیش از کد.

اجرای آزمون‌ها با استفاده از رابط خط فرمان¶

بسته‌ی test را می‌توان به‌کمک گزینه‌ی -m به‌صورت یک اسکریپت برای اجرای بدنه‌ی آزمون‌های رگرسیون پایتون اجرا کرد: python -m test. در پشت صحنه، این بسته از test.regrtest استفاده می‌کند؛ فراخوانی python -m test.regrtest که در نسخه‌های پیشین پایتون استفاده می‌شد، همچنان کار می‌کند. اجرای اسکریپت به‌تنهایی به‌طور خودکار اجرای همه‌ی آزمون‌های رگرسیون موجود در بسته‌ی test را آغاز می‌کند. این کار با یافتن همه‌ی ماژول‌های موجود در بسته که نامشان با test_ شروع می‌شود، ایمپورت کردن آن‌ها، و اجرای تابع test_main() در صورت وجود، یا بارگذاری آزمون‌ها از طریق unittest.TestLoader.loadTestsFromModule در صورت نبود test_main انجام می‌شود. نام آزمون‌های مورد نظر برای اجرا نیز می‌تواند به اسکریپت داده شود. مشخص کردن یک آزمون رگرسیون به‌صورت تکی (python -m test test_spam) خروجی را به حداقل می‌رساند و فقط چاپ می‌کند که آزمون موفقیت‌آمیز بوده یا شکست خورده است.

اجرای مستقیم test به شما امکان می‌دهد تعیین کنید چه منابعی برای استفاده در آزمون‌ها در دسترس باشند. این کار را با استفاده از گزینه -u خط فرمان انجام می‌دهید. مشخص کردن all به‌عنوان مقدار گزینه -u تمام منابع ممکن را فعال می‌کند: python -m test -uall. اگر همه منابع به‌جز یک منبع مطلوب باشند (حالت رایج‌تر)، می‌توانید فهرستی جداشده با ویرگول از منابعی که مطلوب نیستند را پس از all ذکر کنید. فرمان python -m test -uall,-audio,-largefile، test را با همه منابع به‌جز منابع audio و largefile اجرا می‌کند. برای دریافت فهرستی از همه منابع و گزینه‌های بیشتر خط فرمان، python -m test -h را اجرا کنید.

برخی روش‌های دیگر برای اجرای آزمون‌های رگرسیون، به این بستگی دارند که آزمون‌ها روی کدام سکو اجرا می‌شوند. در یونیکس، می‌توانید make test را در پوشه‌ی سطح بالایی که پایتون در آن ساخته شده است اجرا کنید. در ویندوز، اجرای rt.bat از پوشه‌ی PCbuild خود، تمام آزمون‌های رگرسیون را اجرا خواهد کرد.

اضافه شده در نسخه‌ی 3.14: خروجی به‌طور پیش‌فرض رنگی است و می‌توان آن را با استفاده از متغیرهای محیطی کنترل کرد.

`test.support` --- ابزارهایی برای بدنه‌ی آزمون پایتون¶

ماژول test.support از بدنه‌ی آزمون‌های رگرسیون پایتون پشتیبانی می‌کند.

توجه

test.support یک ماژول عمومی نیست. این ماژول در اینجا مستند شده است تا به توسعه‌دهندگان پایتون در نوشتن آزمون‌ها کمک کند. API این ماژول در معرض تغییر است و ممکن است بین نسخه‌ها بدون ملاحظات سازگاری با نسخه‌های پیشین تغییر کند.

این ماژول استثناهای زیر را تعریف می‌کند:

exception test.support.TestFailed¶: استثنایی که هنگام شکست یک آزمون پرتاب می‌شود. این استثنا به نفع آزمون‌های مبتنی بر unittest و متدهای ادعا در unittest.TestCase منسوخ شده است.

exception test.support.ResourceDenied¶: زیرکلاسی از unittest.SkipTest. هنگامی که یک منبع (مانند اتصال شبکه) در دسترس نباشد، پرتاب می‌شود. توسط تابع requires() پرتاب می‌شود.

ماژول test.support ثابت‌های زیر را تعریف می‌کند:

test.support.verbose¶: هنگامی که خروجی پرگو فعال باشد، True است. اگر اطلاعات دقیق‌تری درباره یک آزمون در حال اجرا مورد نیاز باشد، باید بررسی شود. verbose توسط test.regrtest تنظیم می‌شود.

test.support.is_jython¶: اگر مفسر در حال اجرا Jython باشد، True است.

test.support.is_android¶: اگر sys.platform برابر android باشد، True است.

test.support.is_emscripten¶: True اگر sys.platform برابر emscripten باشد.

test.support.is_wasi¶: True اگر sys.platform برابر wasi باشد.

test.support.is_apple_mobile¶: اگر sys.platform برابر ios، tvos یا watchos باشد، True است.

test.support.is_apple¶: اگر sys.platform برابر darwin باشد یا is_apple_mobile برابر True باشد، True است.

test.support.unix_shell¶: مسیر پوسته اگر در ویندوز نباشد؛ در غیر این صورت None.

test.support.LOOPBACK_TIMEOUT¶

مهلت به ثانیه برای آزمون‌هایی که از یک سرور شبکه‌ای گوش‌دهنده به رابط حلقه برگشت محلی شبکه مانند 127.0.0.1 استفاده می‌کنند.

مهلت زمانی به‌اندازه کافی طولانی است تا از شکست آزمون جلوگیری کند: در نظر گرفته شده است که کلاینت و سرور می‌توانند در نخ‌های مختلف یا حتی فرآیندهای مختلف اجرا شوند.

مهلت زمانی باید برای متدهای connect()، recv() و send() در socket.socket به‌اندازه کافی طولانی باشد.

Its default value is 10 seconds.

همچنین INTERNET_TIMEOUT را ببینید.

test.support.INTERNET_TIMEOUT¶

مهلت زمانی بر حسب ثانیه برای درخواست‌های شبکه‌ای که به سمت اینترنت ارسال می‌شوند.

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

معمولاً، یک مهلت زمانی با استفاده از INTERNET_TIMEOUT نباید یک آزمون را به‌عنوان شکست‌خورده علامت‌گذاری کند، بلکه باید در عوض آن آزمون را رد کند: transient_internet() را ببینید.

مقدار پیش‌فرض آن ۱ دقیقه است.

همچنین LOOPBACK_TIMEOUT را ببینید.

test.support.SHORT_TIMEOUT¶

مهلت به ثانیه برای علامت‌گذاری یک آزمون به‌عنوان شکست‌خورده، اگر اجرای آن «بیش از حد طولانی» شود.

مقدار مهلت زمانی به گزینه‌ی خط فرمان --timeout در regrtest بستگی دارد.

اگر آزمونی که از SHORT_TIMEOUT استفاده می‌کند، روی بات‌های ساخت کند (buildbots) شروع به شکست‌های تصادفی کرد، به‌جای آن از LONG_TIMEOUT استفاده کنید.

مقدار پیش‌فرض آن ۳۰ ثانیه است.

test.support.LONG_TIMEOUT¶

مهلت بر حسب ثانیه برای تشخیص زمانی که یک آزمون آویزان می‌شود.

این مقدار به‌اندازه‌ی کافی طولانی است تا خطر شکست آزمون در کندترین بات‌های ساخت پایتون (buildbots) را کاهش دهد. نباید از آن برای علامت‌گذاری یک آزمون به‌عنوان شکست‌خورده استفاده شود، اگر آزمون «بیش از حد» طول بکشد. مقدار مهلت زمانی به گزینه‌ی خط فرمان --timeout در regrtest بستگی دارد.

مقدار پیش‌فرض آن ۵ دقیقه است.

همچنین ببینید LOOPBACK_TIMEOUT، INTERNET_TIMEOUT و SHORT_TIMEOUT.

test.support.PGO¶: زمانی تنظیم می‌شود که بتوان آزمون‌ها را در صورتی که برای PGO مفید نیستند، رد کرد.

test.support.PIPE_MAX_SIZE¶: ثابتی که احتمالاً از اندازه‌ی بافر پایپ سیستم‌عامل زیرین بزرگ‌تر است، تا نوشتن‌ها مسدودکننده شوند.

test.support.Py_DEBUG¶: True اگر پایتون با تعریف‌شدن ماکروی Py_DEBUG ساخته شده باشد، یعنی اگر پایتون در حالت اشکال‌زدایی ساخته شده باشد.

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

test.support.SOCK_MAX_SIZE¶: ثابتی که احتمالاً از اندازه‌ی بافر سوکت سیستم‌عامل زیرین بزرگ‌تر است، تا نوشتن‌ها مسدودکننده شوند.

test.support.TEST_SUPPORT_DIR¶: به پوشه‌ی سطح بالایی که شامل test.support است، تنظیم می‌شود.

test.support.TEST_HOME_DIR¶: به پوشه‌ی سطح بالا برای بسته‌ی آزمون تنظیم شده است.

test.support.TEST_DATA_DIR¶: روی پوشه‌ی data درون بسته‌ی آزمون تنظیم شده است.

test.support.MAX_Py_ssize_t¶: برای آزمون‌های حافظه‌ی بزرگ، آن را روی sys.maxsize تنظیم کنید.

test.support.max_memuse¶: توسط set_memlimit() به‌عنوان محدودیت حافظه برای آزمون‌های حافظه‌ی بزرگ تنظیم می‌شود. با MAX_Py_ssize_t محدود می‌شود.

test.support.real_max_memuse¶: توسط set_memlimit() به‌عنوان محدودیت حافظه برای آزمایش‌های با حافظه‌ی زیاد تنظیم می‌شود. به MAX_Py_ssize_t محدود نیست.

test.support.MISSING_C_DOCSTRINGS¶

اگر پایتون بدون رشته‌مستندها ساخته شده باشد (ماکروی WITH_DOC_STRINGS تعریف‌نشده باشد)، روی True تنظیم می‌شود. گزینه‌ی configure --without-doc-strings را ببینید.

همچنین متغیر HAVE_DOCSTRINGS را ببینید.

test.support.HAVE_DOCSTRINGS¶

اگر رشته مستندات توابع در دسترس باشند، روی True تنظیم می‌شود. گزینه‌ی python -OO را ببینید، که رشته مستندات توابع پیاده‌سازی‌شده در پایتون را حذف می‌کند.

همچنین متغیر MISSING_C_DOCSTRINGS را ببینید.

test.support.TEST_HTTP_URL¶: URL یک سرور HTTP اختصاصی را برای آزمون‌های شبکه تعریف کنید.

test.support.ALWAYS_EQ¶: شیءای که با هر چیزی برابر است. برای آزمایش مقایسه‌ی نوع‌های مختلط استفاده می‌شود.

test.support.NEVER_EQ¶: شیءای که با هیچ چیزی برابر نیست (حتی با ALWAYS_EQ). برای آزمایش مقایسه‌ی نوع‌های مختلط استفاده می‌شود.

test.support.LARGEST¶: شیءای که از هر چیزی (به‌جز خودش) بزرگ‌تر است. برای آزمایش مقایسه‌ی نوع‌های مختلط استفاده می‌شود.

test.support.SMALLEST¶: شیءای که از هر چیزی (به‌جز خودش) کوچک‌تر است. برای آزمایش مقایسه‌ی نوع‌های مختلط استفاده می‌شود.

ماژول test.support توابع زیر را تعریف می‌کند:

test.support.busy_retry(timeout, err_msg=None, /, *, error=True)¶

بدنه حلقه را تا زمانی اجرا کنید که break حلقه را متوقف کند.

پس از timeout ثانیه، اگر error درست باشد، استثنای AssertionError پرتاب می‌شود، یا اگر error نادرست باشد، فقط حلقه متوقف می‌شود.

مثال:

for _ in support.busy_retry(support.SHORT_TIMEOUT):
    if check():
        break

مثالی از کاربرد error=False:

for _ in support.busy_retry(support.SHORT_TIMEOUT, error=False):
    if check():
        break
else:
    raise RuntimeError('my custom error')

test.support.sleeping_retry(timeout, err_msg=None, /, *, init_delay=0.010, max_delay=1.0, error=True)¶

راهبرد انتظاری که عقب‌نشینی نمایی (exponential backoff) را اعمال می‌کند.

بدنه حلقه را تا زمانی که break حلقه را متوقف کند، اجرا کنید. در هر تکرار حلقه مکث کنید، اما نه در تکرار نخست. تأخیر مکث در هر تکرار دو برابر می‌شود (حداکثر تا max_delay ثانیه).

برای استفاده از پارامترها، مستندات busy_retry() را ببینید.

مثالی از پرتاب استثنا پس از SHORT_TIMEOUT ثانیه:

for _ in support.sleeping_retry(support.SHORT_TIMEOUT):
    if check():
        break

مثالی از کاربرد error=False:

for _ in support.sleeping_retry(support.SHORT_TIMEOUT, error=False):
    if check():
        break
else:
    raise RuntimeError('my custom error')

test.support.is_resource_enabled(resource)¶: اگر resource فعال و در دسترس باشد، True را برمی‌گرداند. فهرست منابع در دسترس فقط زمانی تنظیم می‌شود که test.regrtest در حال اجرای آزمون‌ها باشد.

test.support.get_resource_value(resource)¶: مقدار مشخص‌شده برای resource را برمی‌گرداند (به‌صورت -u resource=value). اگر resource غیرفعال باشد یا هیچ مقداری مشخص نشده باشد، None را برمی‌گرداند.

test.support.python_is_optimized()¶: اگر پایتون با -O0 یا -Og ساخته نشده باشد، True را برمی‌گرداند.

test.support.with_pymalloc()¶: _testcapi.WITH_PYMALLOC را برمی‌گرداند.

test.support.requires(resource, msg=None)¶: اگر resource در دسترس نباشد، ResourceDenied را پرتاب می‌کند. اگر این استثنا پرتاب شود، msg آرگومان ResourceDenied خواهد بود. اگر توسط تابعی فراخوانی شود که __name__ آن '__main__' است، همیشه True را برمی‌گرداند. هنگامی که آزمون‌ها توسط test.regrtest اجرا می‌شوند، استفاده می‌شود.

test.support.sortdict(dict)¶: یک بازنمایی (repr) از dict با کلیدهای مرتب‌شده برمی‌گرداند.

test.support.findfile(filename, subdir=None)¶

مسیر پرونده‌ای با نام filename را برمی‌گرداند. اگر هیچ مورد منطبقی یافت نشد، filename برگردانده می‌شود. این معادل شکست نیست، زیرا ممکن است مسیر پرونده باشد.

تنظیم subdir یک مسیر نسبی را برای استفاده در یافتن پرونده مشخص می‌کند، به‌جای جست‌وجوی مستقیم در پوشه‌های مسیر.

test.support.get_pagesize()¶: دریافت اندازه‌ی یک صفحه بر حسب بایت.

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

test.support.setswitchinterval(interval)¶: sys.setswitchinterval() را روی interval داده‌شده تنظیم می‌کند. یک بازه‌ی حداقلی برای سیستم‌های اندروید تعریف می‌کند تا از هنگ کردن سیستم جلوگیری شود.

test.support.check_impl_detail(**guards)¶

از این بررسی برای محافظت از آزمون‌های مختص پیاده‌سازی CPython یا برای اجرای آن‌ها فقط روی پیاده‌سازی‌های محافظت‌شده توسط آرگومان‌ها استفاده کنید. این تابع بسته به پلتفرم میزبان، True یا False برمی‌گرداند. نمونه کاربرد:

check_impl_detail()               # Only on CPython (default).
check_impl_detail(jython=True)    # Only on Jython.
check_impl_detail(cpython=False)  # Everywhere except CPython.

test.support.set_memlimit(limit)¶: مقادیر max_memuse و real_max_memuse را برای آزمون‌های حافظه بزرگ تنظیم کنید.

test.support.record_original_stdout(stdout)¶: مقدار را از stdout ذخیره کنید. این برای نگه‌داری stdout در لحظه‌ای که regrtest آغاز شد، در نظر گرفته شده است.

test.support.get_original_stdout()¶: stdout اصلی تنظیم‌شده توسط record_original_stdout() را برمی‌گرداند، یا اگر تنظیم نشده باشد، sys.stdout را برمی‌گرداند.

test.support.args_from_interpreter_flags()¶: فهرستی از آرگومان‌های خط فرمان را برمی‌گرداند که تنظیمات فعلی را در sys.flags و sys.warnoptions بازتولید می‌کنند.

test.support.optim_args_from_interpreter_flags()¶: فهرستی از آرگومان‌های خط فرمان را برمی‌گرداند که تنظیمات بهینه‌سازی فعلی را در sys.flags بازتولید می‌کنند.

test.support.captured_stdin()¶

test.support.captured_stdout()¶

test.support.captured_stderr()¶

یک مدیر زمینه که به‌طور موقت جریان نام‌برده‌شده را با یک شیء io.StringIO جایگزین می‌کند.

مثال استفاده با جریان‌های خروجی:

with captured_stdout() as stdout, captured_stderr() as stderr:
    print("hello")
    print("error", file=sys.stderr)
assert stdout.getvalue() == "hello\n"
assert stderr.getvalue() == "error\n"

نمونه کاربرد با جریان ورودی:

with captured_stdin() as stdin:
    stdin.write('hello\n')
    stdin.seek(0)
    # call test code that consumes from sys.stdin
    captured = input()
self.assertEqual(captured, "hello")

test.support.disable_faulthandler()¶: یک مدیر زمینه که faulthandler را به‌طور موقت غیرفعال می‌کند.

test.support.gc_collect()¶: تا حد امکان، اشیاء را مجبور به جمع‌آوری شدن می‌کند. این کار لازم است، زیرا زباله‌روبی آزادسازی به‌موقع را تضمین نمی‌کند. این بدان معناست که ممکن است متدهای __del__ دیرتر از آنچه انتظار می‌رود فراخوانی شوند و ارجاع‌های ضعیف برای مدت طولانی‌تری از آنچه انتظار می‌رود زنده بمانند.

test.support.disable_gc()¶: یک مدیر زمینه که در هنگام ورود، زباله‌روبی را غیرفعال می‌کند. در هنگام خروج، زباله‌روبی به حالت پیشین خود بازمی‌گردد.

test.support.swap_attr(obj, attr, new_val)¶

مدیر زمینه برای جایگزین کردن یک ویژگی با یک شیء جدید.

استفاده:

with swap_attr(obj, "attr", 5):
    ...

این دستور obj.attr را در طول بلوک with روی ۵ تنظیم می‌کند و مقدار پیشین را در پایان بلوک بازمی‌گرداند. اگر attr روی obj وجود نداشته باشد، ایجاد می‌شود و سپس در پایان بلوک حذف می‌شود.

مقدار قبلی (یا None اگر وجود نداشته باشد) به هدف بند "as" انتساب داده می‌شود، اگر این بند وجود داشته باشد.

test.support.swap_item(obj, attr, new_val)¶

مدیر زمینه برای جایگزینی یک آیتم با یک شیء جدید.

استفاده:

with swap_item(obj, "item", 5):
    ...

این کار obj["item"] را در طول مدت بلوک with روی ۵ تنظیم می‌کند و مقدار پیشین را در پایان بلوک بازمی‌گرداند. اگر item در obj وجود نداشته باشد، ایجاد می‌شود و سپس در پایان بلوک حذف می‌شود.

مقدار قبلی (یا None اگر وجود نداشته باشد) به هدف بند "as" انتساب داده می‌شود، اگر این بند وجود داشته باشد.

test.support.flush_std_streams()¶: متد flush() را روی sys.stdout و سپس روی sys.stderr فراخوانی کنید. می‌توان از آن برای اطمینان از سازگاری ترتیب گزارش‌ها پیش از نوشتن در stderr استفاده کرد.

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

test.support.print_warning(msg)¶: هشداری را در sys.__stderr__ چاپ کنید. پیام را به‌صورت f"Warning -- {msg}" قالب‌بندی کنید. اگر msg از چند خط تشکیل شده باشد، پیشوند "Warning -- " را به هر خط اضافه کنید.

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

test.support.wait_process(pid, *, exitcode, timeout=None)¶

صبر کنید تا فرایند pid به پایان برسد و بررسی کنید که کد خروجی فرایند exitcode باشد.

اگر کد خروجی فرایند با exitcode برابر نباشد، یک AssertionError پرتاب می‌شود.

اگر فرایند بیش از timeout ثانیه طول بکشد (SHORT_TIMEOUT به‌طور پیش‌فرض)، فرایند را خاتمه دهید و یک AssertionError را پرتاب کنید. قابلیت مهلت در ویندوز در دسترس نیست.

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

test.support.calcobjsize(fmt)¶: اندازه‌ی PyObject که اعضای ساختار آن توسط fmt تعریف شده‌اند را برمی‌گرداند. مقدار بازگشتی شامل اندازه‌ی سرآیند شیء پایتون و هم‌ترازی است.

test.support.calcvobjsize(fmt)¶: اندازه‌ی PyVarObject را که اعضای ساختار آن توسط fmt تعریف شده‌اند، برمی‌گرداند. مقدار برگردانده‌شده شامل اندازه‌ی سرآیند شیء پایتون و هم‌ترازی است.

test.support.checksizeof(test, o, size)¶: برای مورد آزمون test، ادعا کنید که sys.getsizeof برای o به‌همراه اندازه‌ی سرآیند‌ی GC برابر با size است.

@test.support.anticipate_failure(condition)¶: دکوراتوری برای علامت‌گذاری مشروط آزمون‌ها با @unittest.expectedFailure. هر استفاده‌ای از این دکوراتور باید دارای یک کامنت همراه باشد که موضوع مرتبط در سامانه پیگیری را مشخص کند.

test.support.system_must_validate_cert(f)¶: دکوراتوری که در صورت شکست اعتبارسنجی گواهی TLS، آزمون دکوراته‌شده را رد می‌کند.

@test.support.run_with_locale(catstr, *locales)¶: یک دکوراتور برای اجرای یک تابع در یک locale متفاوت، که پس از پایان اجرا، locale را به‌درستی بازنشانی می‌کند. catstr دسته locale (locale category) به‌صورت یک رشته است (برای مثال "LC_ALL"). locales ارسال‌شده به‌ترتیب آزمایش می‌شوند و اولین locale معتبر استفاده می‌شود.

@test.support.run_with_tz(tz)¶: دکوراتوری برای اجرای یک تابع در یک منطقه‌ی زمانی مشخص، که پس از پایان آن، منطقه‌ی زمانی را به‌درستی بازنشانی می‌کند.

@test.support.requires_freebsd_version(*min_version)¶: دکوراتور برای حداقل نسخه هنگام اجرای آزمون روی FreeBSD. اگر نسخه FreeBSD کمتر از حداقل باشد، آزمون رد می‌شود.

@test.support.requires_linux_version(*min_version)¶: دکوراتور برای حداقل نسخه هنگام اجرای آزمون در لینوکس. اگر نسخه‌ی لینوکس کمتر از حداقل باشد، آزمون رد می‌شود.

@test.support.requires_mac_version(*min_version)¶: دکوراتور برای حداقل نسخه هنگام اجرای آزمون روی macOS. اگر نسخه macOS کمتر از حداقل باشد، آزمون رد می‌شود.

@test.support.requires_gil_enabled¶: دکوراتور برای رد کردن آزمون‌ها در ساخت نخ‌آزاد (free-threaded build). اگر GIL غیرفعال باشد، آزمون رد می‌شود.

@test.support.requires_IEEE_754¶: دکوراتور برای رد کردن آزمون‌ها روی سکوهای غیر IEEE 754.

@test.support.requires_zlib¶: دکوراتوری برای رد کردن آزمون‌ها در صورتی که zlib وجود نداشته باشد.

@test.support.requires_gzip¶: دکوراتوری برای پرش از آزمون‌ها در صورتی که gzip وجود نداشته باشد.

@test.support.requires_bz2¶: دکوراتوری برای رد کردن آزمون‌ها در صورتی که bz2 وجود نداشته باشد.

@test.support.requires_lzma¶: دکوراتوری برای پرش از آزمون‌ها در صورتی که lzma وجود نداشته باشد.

@test.support.requires_resource(resource)¶: دکوراتوری برای رد کردن آزمون‌ها در صورتی که resource در دسترس نباشد.

@test.support.requires_docstrings¶: دکوراتوری برای اجرای آزمون فقط در صورت HAVE_DOCSTRINGS.

@test.support.requires_limited_api¶: دکوراتوری برای اجرای آزمون تنها در صورتی که Limited C API در دسترس باشد.

@test.support.cpython_only¶: دکوراتور برای آزمون‌هایی که فقط در CPython کاربرد دارند.

@test.support.impl_detail(msg=None, **guards)¶: دکوراتوری برای فراخوانی check_impl_detail() روی guards. اگر آن False برگرداند، از msg به‌عنوان دلیل پرش از آزمون استفاده می‌کند.

@test.support.thread_unsafe(reason=None)¶: دکوراتوری برای علامت‌گذاری آزمون‌ها به‌عنوان ناامن برای نخ‌ها. این آزمون همیشه در یک نخ اجرا می‌شود، حتی زمانی که با --parallel-threads فراخوانی شود.

@test.support.no_tracing¶: دکوراتوری برای خاموش کردن موقت ردگیری در طول مدت آزمون.

@test.support.refcount_test¶: دکوراتوری برای آزمون‌هایی که با شمارش ارجاع سروکار دارند. این دکوراتور آزمون را اجرا نمی‌کند، مگر اینکه توسط CPython اجرا شود. هر تابع ردگیری در طول اجرای آزمون غیرفعال می‌شود تا از شمارش‌های ارجاع غیرمنتظره ناشی از تابع ردگیری جلوگیری شود.

@test.support.bigmemtest(size, memuse, dry_run=True)¶

دکوراتور برای آزمون‌های bigmem.

size اندازه‌ی درخواستی برای آزمون است (در واحدهای دلخواهی که آزمون آن‌ها را تفسیر می‌کند). memuse تعداد بایت‌ها به ازای هر واحد برای آزمون، یا برآورد خوبی از آن است. برای مثال، می‌توان آزمونی را که به دو بافر بایتی، هر یک به اندازه‌ی ۴ GiB نیاز دارد، با @bigmemtest(size=_4G, memuse=2) آراست.

آرگومان size معمولاً به‌عنوان یک آرگومان اضافی به متد آزمون دکوریت‌شده ارسال می‌شود. اگر dry_run برابر True باشد، مقدار ارسال‌شده به متد آزمون ممکن است کمتر از مقدار درخواستی باشد. اگر dry_run برابر False باشد، به این معناست که آزمون وقتی -M مشخص نشده باشد از اجراهای ساختگی پشتیبانی نمی‌کند.

@test.support.bigaddrspacetest¶: دکوراتوری برای آزمون‌هایی که فضای آدرس را پر می‌کنند.

test.support.linked_to_musl()¶: اگر مدرکی مبنی بر کامپایل شدن مفسر با musl وجود نداشته باشد، False برمی‌گرداند؛ در غیر این صورت یک سه‌تایی نسخه برمی‌گرداند: اگر نسخه ناشناخته باشد (0, 0, 0) و اگر نسخه شناخته‌شده باشد، نسخه واقعی را. برای استفاده در دکوراتورهای skip در نظر گرفته شده است. فرض می‌شود emscripten و wasi با musl کامپایل شده باشند؛ در غیر این صورت platform.libc_ver بررسی می‌شود.

test.support.check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)¶: آزمون خطاهای سینتکسی در statement با تلاش برای کامپایل کردن statement انجام می‌شود. testcase نمونه‌ی unittest برای آزمون است. errtext عبارت باقاعده‌ای است که باید با نمایش رشته‌ای SyntaxError پرتاب‌شده مطابقت داشته باشد. اگر lineno None نباشد، با خط استثنا مقایسه می‌شود. اگر offset None نباشد، با آفست استثنا مقایسه می‌شود.

test.support.open_urlresource(url, *args, **kw)¶: url را باز می‌کند. اگر باز کردن ناموفق باشد، TestFailed را پرتاب می‌کند.

test.support.reap_children()¶: هر زمان که زیرفرایندها آغاز می‌شوند، از این در پایان test_main استفاده کنید. این کار کمک می‌کند تا اطمینان حاصل شود که هیچ‌کدام از فرزندان اضافی (زامبی‌ها) باقی نمی‌مانند که منابع را اشغال کنند و هنگام جست‌وجو برای نشت‌های مرجع (refleaks) مشکل ایجاد کنند.

test.support.get_attribute(obj, name)¶: یک ویژگی دریافت می‌کند؛ اگر AttributeError پرتاب شد، unittest.SkipTest را ایجاد میکند.

test.support.catch_unraisable_exception()¶

مدیر زمینه‌ای که استثنای غیرقابل‌پرتاب را با استفاده از sys.unraisablehook() می‌گیرد.

ذخیره‌سازی مقدار استثنا (cm.unraisable.exc_value) یک چرخه‌ی ارجاع ایجاد می‌کند. این چرخه‌ی ارجاع هنگامی که مدیر زمینه خارج می‌شود، به‌صراحت شکسته می‌شود.

ذخیره‌کردن شیء (cm.unraisable.object) می‌تواند باعث احیای آن شود، اگر روی شیءای تنظیم شده باشد که در حال نهایی‌سازی است. خروج از مدیر زمینه، شیء ذخیره‌شده را پاک می‌کند.

استفاده:

with support.catch_unraisable_exception() as cm:
    # code creating an "unraisable exception"
    ...

    # check the unraisable exception: use cm.unraisable
    ...

# cm.unraisable attribute no longer exists at this point
# (to break a reference cycle)

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

test.support.load_package_tests(pkg_dir, loader, standard_tests, pattern)¶

پیاده‌سازی عام پروتکل load_tests در unittest برای استفاده در بسته‌های آزمون. pkg_dir پوشه‌ی ریشه‌ی بسته است؛ loader، standard_tests و pattern آرگومان‌های مورد انتظار load_tests هستند. در موارد ساده، پرونده __init__.py بسته‌ی آزمون می‌تواند به‌صورت زیر باشد:

import os
from test.support import load_package_tests

def load_tests(*args):
    return load_package_tests(os.path.dirname(__file__), *args)

test.support.detect_api_mismatch(ref_api, other_api, *, ignore=())¶

مجموعه‌ای از ویژگی‌ها، توابع یا متدهای ref_api را برمی‌گرداند که در other_api یافت نمی‌شوند، به‌جز فهرست تعریف‌شده‌ای از آیتم‌هایی که باید در این بررسی نادیده گرفته شوند و در ignore مشخص شده‌اند.

به‌طور پیش‌فرض، ویژگی‌های خصوصی‌ای که با '_' آغاز می‌شوند نادیده گرفته می‌شوند، اما همه‌ی متدهای جادویی، یعنی آن‌هایی که با '__' آغاز می‌شوند و به آن ختم می‌شوند، شامل می‌شوند.

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

test.support.patch(test_instance, object_to_patch, attr_name, new_value)¶: object_to_patch.attr_name را با new_value بازنویسی می‌کند. همچنین یک رویه‌ی پاک‌سازی به test_instance اضافه می‌کند تا object_to_patch را برای attr_name به حالت پیشین بازگرداند. attr_name باید یک ویژگی معتبر برای object_to_patch باشد.

test.support.run_in_subinterp(code)¶: code را در زیرمفسر اجرا می‌کند. اگر tracemalloc فعال باشد، unittest.SkipTest را پرتاب می‌کند.

@test.support.isolation.runInSubprocess(*, options=(), env=None, timeout=None)¶

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

هنگامی که یک متد با دکوراتور آراسته شود، تنها همان متد در یک زیرفرایند اجرا می‌شود؛ همه‌ی ثابت‌های آزمایشی (setUp() / tearDown()، setUpClass() / tearDownClass() و setUpModule() / tearDownModule()) هم در فرایند والد (مانند معمول) و هم در زیرفرایند، پیرامون متد اجرا می‌شوند.

هنگامی که یک کلاس آراسته می‌شود، کل کلاس در یک زیرفرایند واحد اجرا می‌شود، و setUpClass()، tearDownClass()، setUp() و tearDown() هرکدام یک بار در زیرفرایند اجرا می‌شوند و در فرایند والد رد می‌شوند. شکست یا رد شدن setUpClass() در زیرفرایند، برای کل کلاس گزارش می‌شود. setUpModule() نمی‌تواند با دکوراتور کلاس کنترل شود، بنابراین همچنان در فرایند والد نیز اجرا می‌شود؛ در صورت نیاز آن را با runningInSubprocess بیازمایید.

زیرفرایند، منابع فعال‌شده (-u)، محدودیت حافظه (-M) و سطح جزئیات (-v) را از اجرای آزمون والد به ارث می‌برد، به‌گونه‌ای که requires_resource()، requires()، bigmemtest() و موارد مشابه در هر دو فرایند رفتار یکسانی داشته باشند.

options is a sequence of interpreter command line options to run the subprocess with, and env is a mapping of environment variables to set in it, on top of the inherited environment. A value of None in env unsets the variable. Note that -E and -I make the subprocess ignore the PYTHON* environment variables, including PYTHONPATH.

timeout is the number of seconds to wait for the subprocess; the test is reported as an error if it does not complete in time. By default there is no timeout, and a hung test is left to the timeout of the test runner.

این آزمون در سکوهای بدون پشتیبانی از subprocess نادیده گرفته می‌شود.

test.support.isolation.runningInSubprocess¶: در حین اجرای کد در زیرفرایند ایزوله‌ی ایجادشده توسط runInSubprocess()، True و در غیر این صورت False است (از جمله در فرایند والد و در یک اجرای آزمون عادی و غیرایزوله). ثابت‌های آزمایشیی مانند setUp()، tearDown()، setUpClass()، tearDownClass()، setUpModule() و tearDownModule() می‌توانند آن را آزمایش کنند تا انتخاب کنند کدام کد در زیرفرایند اجرا شود.

test.support.check_free_after_iterating(test, iter, cls, args=())¶: ادعا کنید که نمونه‌های cls پس از پیمایش، آزاد شده‌اند.

test.support.missing_compiler_executable(cmd_names=[])¶: وجود پرونده‌های اجرایی کامپایلر با نام‌های فهرست‌شده در cmd_names، یا در صورت خالی بودن cmd_names وجود همه‌ی پرونده‌های اجرایی کامپایلر را بررسی کنید و نخستین پرونده اجرایی مفقود را برگردانید؛ اگر هیچ مورد مفقودی یافت نشد، None برگردانید.

test.support.check__all__(test_case, module, name_of_module=None, extra=(), not_exported=())¶

اطمینان حاصل کنید که متغیر __all__ در module شامل تمام نام‌های عمومی است.

نام‌های عمومی ماژول (API آن) به‌صورت خودکار بر اساس این‌که با قرارداد نام عمومی مطابقت داشته باشند و در module تعریف شده باشند، تشخیص داده می‌شوند.

آرگومان name_of_module می‌تواند (به‌صورت یک رشته یا تاپلی از رشته‌ها) مشخص کند که یک API ممکن است در چه ماژول‌هایی تعریف شده باشد تا به‌عنوان API عمومی تشخیص داده شود. یکی از موارد این حالت وقتی است که module بخشی از API عمومی خود را از ماژول‌های دیگر ایمپورت می‌کند، احتمالاً از یک بک‌اند C (مانند csv و _csv آن).

آرگومان extra می‌تواند مجموعه‌ای از نام‌ها باشد که در غیر این صورت به‌طور خودکار به‌عنوان «عمومی» شناسایی نمی‌شدند، مانند اشیایی که ویژگی __module__ مناسب ندارند. در صورت ارائه، به موارد شناسایی‌شده به‌طور خودکار اضافه می‌شود.

آرگومان not_exported می‌تواند مجموعه‌ای از نام‌ها باشد که نباید به‌عنوان بخشی از API عمومی تلقی شوند، حتی اگر نام‌هایشان خلاف آن را نشان می‌دهند.

نمونه استفاده:

import bar
import foo
import unittest
from test import support

class MiscTestCase(unittest.TestCase):
    def test__all__(self):
        support.check__all__(self, foo)

class OtherTestCase(unittest.TestCase):
    def test__all__(self):
        extra = {'BAR_CONST', 'FOO_CONST'}
        not_exported = {'baz'}  # Undocumented name.
        # bar imports part of its API from _bar.
        support.check__all__(self, bar, ('bar', '_bar'),
                             extra=extra, not_exported=not_exported)

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

test.support.skip_if_broken_multiprocessing_synchronize()¶: در صورتی که ماژول multiprocessing.synchronize موجود نبود، هیچ پیاده‌سازی سمافور در دسترس نبود، یا ایجاد یک قفل باعث پرتاب OSError شد، از آزمون‌ها صرف‌نظر کنید.

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

test.support.check_disallow_instantiation(test_case, tp, *args, **kwds)¶: ادعا کنید که نوع tp نمی‌تواند با استفاده از args و kwds نمونه‌سازی شود.

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

test.support.adjust_int_max_str_digits(max_digits)¶: این تابع یک مدیر زمینه برمی‌گرداند که تنظیم سراسری sys.set_int_max_str_digits() را در طول عمر زمینه تغییر می‌دهد تا امکان اجرای کد آزمونی که به محدودیت متفاوتی در تعداد ارقام هنگام تبدیل بین عدد صحیح و رشته نیاز دارد، فراهم شود.

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

ماژول test.support کلاس‌های زیر را تعریف می‌کند:

class test.support.SuppressCrashReport¶

یک مدیر زمینه که برای تلاش جهت جلوگیری از نمایش پنجره‌های بازشوی محاوره‌ای فروپاشی در آزمون‌هایی که انتظار می‌رود یک زیرفرایند را دچار خرابی کنند، به کار می‌رود.

در ویندوز، پنجره‌های محاوره‌ای گزارش خطای ویندوز (Windows Error Reporting) را با استفاده از SetErrorMode غیرفعال می‌کند.

در UNIX، از resource.setrlimit() برای تنظیم حد نرم resource.RLIMIT_CORE بر روی ۰ استفاده می‌شود تا از ایجاد پرونده coredump جلوگیری شود.

در هر دو سکو، مقدار پیشین توسط __exit__() بازیابی می‌شود.

class test.support.SaveSignals¶

کلاسی برای ذخیره و بازیابی هندلرهای سیگنالی که توسط مدیر سیگنال پایتون ثبت شده‌اند.

save(self)¶: هندلرهای سیگنال را در دیکشنری‌ای ذخیره کنید که شماره‌های سیگنال را به هندلر فعلی سیگنال نگاشت می‌کند.

restore(self)¶: شماره‌های سیگنال موجود در دیکشنری save() را به هندلر ذخیره‌شده تنظیم کنید.

class test.support.Matcher¶

matches(self, d, **kwargs)¶: تلاش کنید یک دیکشنری را با آرگومان‌های ارائه‌شده تطبیق دهید.

match_value(self, k, dv, v)¶: سعی کنید یک مقدار ذخیره‌شده‌ی منفرد (dv) را با یک مقدار ارائه‌شده (v) مطابقت دهید.

`test.support.socket_helper` --- ابزارهایی برای آزمون‌های سوکت¶

ماژول test.support.socket_helper برای آزمون‌های سوکت پشتیبانی فراهم می‌کند.

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

test.support.socket_helper.IPV6_ENABLED¶: اگر IPv6 روی این میزبان فعال باشد، روی True تنظیم می‌شود، در غیر این صورت روی False.

test.support.socket_helper.find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)¶

یک پورت استفاده‌نشده برمی‌گرداند که باید برای مقیدسازی مناسب باشد. این کار با ایجاد یک سوکت موقتی با خانواده و نوع مشابه پارامتر sock (پیش‌فرض AF_INET، SOCK_STREAM است) و مقیدسازی آن به نشانی میزبان مشخص‌شده (پیش‌فرض 0.0.0.0) در حالی که پورت روی ۰ تنظیم شده است، انجام می‌شود تا یک پورت موقتی استفاده‌نشده از سیستم‌عامل دریافت شود. سپس سوکت موقتی بسته و حذف می‌شود و پورت موقتی برگردانده می‌شود.

در هر آزمونی که در آن لازم است یک سوکت سرور در طول آزمون به یک درگاه خاص مقید شود، باید از این متد یا bind_port() استفاده شود. انتخاب بین این دو به این بستگی دارد که کد فراخواننده در حال ایجاد یک سوکت پایتون باشد یا اینکه لازم باشد یک درگاه استفاده‌نشده در اختیار یک سازنده قرار گیرد یا به یک برنامه‌ی خارجی داده شود (برای مثال، آرگومان -accept در حالت s_server مربوط به openssl). هرجا ممکن است، همیشه bind_port() را به find_unused_port() ترجیح دهید. استفاده از یک درگاه از پیش تعیین‌شده توصیه نمی‌شود، زیرا می‌تواند اجرای هم‌زمان چند نمونه از آزمون را غیرممکن کند؛ این مسئله برای buildbotها مشکل‌ساز است.

test.support.socket_helper.bind_port(sock, host=HOST)¶

سوکت را به یک پورت آزاد مقید می‌کند و شماره‌ی پورت را برمی‌گرداند. برای اطمینان از اینکه از یک پورت مقیدنشده استفاده می‌شود، به پورت‌های موقتی (ephemeral ports) متکی است. این موضوع مهم است، زیرا ممکن است آزمون‌های بسیاری به‌طور همزمان در حال اجرا باشند، به‌ویژه در محیط buildbot. این متد در صورتی استثنا پرتاب می‌کند که sock.family برابر AF_INET و sock.type برابر SOCK_STREAM باشد، و گزینه‌ی SO_REUSEADDR یا SO_REUSEPORT روی سوکت تنظیم‌شده باشد. آزمون‌ها هرگز نباید این گزینه‌های سوکت را برای سوکت‌های TCP/IP تنظیم کنند. تنها حالت برای تنظیم این گزینه‌ها، آزمون کردن چندپخشی (multicasting) از طریق چند سوکت UDP است.

علاوه بر این، اگر گزینه‌ی سوکت SO_EXCLUSIVEADDRUSE در دسترس باشد (یعنی در ویندوز)، روی سوکت تنظیم می‌شود. این کار از مقید شدن هر کس دیگر به میزبان/پورت ما در طول مدت آزمون جلوگیری می‌کند.

test.support.socket_helper.bind_unix_socket(sock, addr)¶: یک سوکت یونیکس را مقید می‌کند و در صورت پرتاب PermissionError، unittest.SkipTest را پرتاب می‌کند.

@test.support.socket_helper.skip_unless_bind_unix_socket¶: دکوراتوری برای اجرای آزمون‌هایی که به یک bind() کارا برای سوکت‌های Unix نیاز دارند.

test.support.socket_helper.transient_internet(resource_name, *, timeout=30.0, errnos=())¶: یک مدیر زمینه که ResourceDenied را هنگامی که مشکلات گوناگون اتصال به اینترنت به‌صورت استثناهایی آشکار می‌شوند، پرتاب می‌کند.

`test.support.script_helper` --- ابزارهایی برای آزمون‌های اجرای پایتون¶

ماژول test.support.script_helper پشتیبانی برای آزمون‌های اجرای اسکریپت پایتون را فراهم می‌کند.

test.support.script_helper.interpreter_requires_environment()¶

اگر sys.executable interpreter برای اینکه اصلاً بتواند اجرا شود به متغیرهای محیطی نیاز داشته باشد، True را برمی‌گرداند.

این برای استفاده با @unittest.skipIf() طراحی شده است تا آزمون‌هایی را علامت‌گذاری کند که نیاز دارند از یک تابع assert_python*() برای راه‌اندازی یک فرایند زیرمفسر در حالت ایزوله (-I) یا حالت بدون محیط (-E) استفاده کنند.

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

تنظیم PYTHONHOME یکی از راه‌ها برای اجرای بیشتر مجموعه‌آزمون در آن شرایط است. PYTHONPATH یا PYTHONUSERSITE متغیرهای محیطی رایج دیگری هستند که ممکن است بر اینکه مفسر بتواند آغاز شود یا نه تأثیر بگذارند.

test.support.script_helper.run_python_until_end(*args, **env_vars)¶: محیط را بر اساس env_vars برای اجرای مفسر در یک زیرفرایند تنظیم کنید. مقادیر می‌توانند شامل __isolated، __cleanenv، __cwd و TERM باشند.

تغییر یافته در نسخه‌ی 3.9: این تابع دیگر نویسه‌های فاصله را از stderr حذف نمی‌کند.

test.support.script_helper.assert_python_ok(*args, **env_vars)¶

ادعا می‌کند که اجرای مفسر با args و متغیرهای محیطی اختیاری env_vars با موفقیت انجام می‌شود (rc == 0) و یک تاپل (return code, stdout, stderr) برمی‌گرداند.

اگر پارامتر فقط کلیدواژه‌ای __cleanenv تنظیم شده باشد، از env_vars به‌عنوان یک محیط تازه استفاده می‌شود.

پایتون در حالت ایزوله اجرا می‌شود (گزینه خط فرمان -I)، مگر اینکه پارامتر فقط کلیدواژه‌ای __isolated روی False تنظیم شده باشد.

تغییر یافته در نسخه‌ی 3.9: این تابع دیگر نویسه‌های فاصله را از stderr حذف نمی‌کند.

test.support.script_helper.assert_python_failure(*args, **env_vars)¶

ادعا می‌کند که اجرای مفسر با args و متغیرهای محیطی اختیاری env_vars شکست می‌خورد (rc != 0) و یک تاپل (return code, stdout, stderr) را بازمی‌گرداند.

برای گزینه‌های بیشتر، assert_python_ok() را ببینید.

تغییر یافته در نسخه‌ی 3.9: این تابع دیگر نویسه‌های فاصله را از stderr حذف نمی‌کند.

test.support.script_helper.spawn_python(*args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, **kw)¶

یک زیرفرایند پایتون را با آرگومان‌های داده‌شده اجرا کنید.

kw آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به subprocess.Popen() هستند. یک شیء subprocess.Popen بازمی‌گرداند.

test.support.script_helper.kill_python(p)¶: فرآیند subprocess.Popen داده‌شده را تا پایان اجرا می‌کند و stdout را برمی‌گرداند.

test.support.script_helper.make_script(script_dir, script_basename, source, omit_suffix=False)¶: اسکریپتی حاوی source در مسیر script_dir و script_basename ایجاد می‌کند. اگر omit_suffix برابر False باشد، .py به نام افزوده می‌شود. مسیر کامل اسکریپت را برمی‌گرداند.

test.support.script_helper.make_zip_script(zip_dir, zip_basename, script_name, name_in_zip=None)¶: یک پرونده zip در zip_dir و zip_basename با پسوند zip ایجاد می‌کند که شامل پرونده‌های موجود در script_name است. name_in_zip نام آرشیو است. یک تاپل شامل (full path, full path of archive name) برمی‌گرداند.

test.support.script_helper.make_pkg(pkg_dir, init_source='')¶: پوشه‌ای به نام pkg_dir ایجاد کنید که شامل یک پرونده __init__ با محتوای init_source باشد.

test.support.script_helper.make_zip_pkg(zip_dir, zip_basename, pkg_name, script_basename, source, depth=1, compiled=False)¶: یک پوشه‌ی بسته‌ی zip با مسیر zip_dir و zip_basename ایجاد کنید که شامل یک پرونده __init__ خالی و یک پرونده script_basename حاوی source باشد. اگر compiled برابر True باشد، هر دو پرونده منبع کامپایل می‌شوند و به بسته‌ی zip اضافه می‌شوند. یک تاپل از مسیر کامل zip و نام بایگانی برای پرونده zip را برگردانید.

`test.support.bytecode_helper` --- ابزارهای پشتیبانی برای آزمون تولید صحیح بایت‌کد¶

ماژول test.support.bytecode_helper پشتیبانی برای آزمون و بازرسی تولید بایت‌کد را فراهم می‌کند.

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

این ماژول کلاس زیر را تعریف می‌کند:

class test.support.bytecode_helper.BytecodeTestCase(unittest.TestCase)¶: این کلاس دارای متدهای ادعای سفارشی برای بازرسی بایت‌کد است.

BytecodeTestCase.get_disassembly_as_string(co)¶: واسازی (disassembly) co را به‌صورت رشته برمی‌گرداند.

BytecodeTestCase.assertInBytecode(x, opname, argval=_UNSPECIFIED)¶: اگر opname یافت شود، instr را برمی‌گرداند، در غیر این صورت AssertionError را پرتاب می‌کند.

BytecodeTestCase.assertNotInBytecode(x, opname, argval=_UNSPECIFIED)¶: اگر opname پیدا شود، AssertionError را پرتاب می‌کند.

`test.support.threading_helper` --- ابزارهایی برای آزمون‌های نخ‌بندی¶

ماژول test.support.threading_helper پشتیبانی از آزمون‌های نخ‌بندی (threading) را فراهم می‌کند.

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

test.support.threading_helper.join_thread(thread, timeout=None)¶: به یک نخ در بازه‌ی timeout ملحق شوید. اگر نخ پس از timeout ثانیه هنوز زنده بود، یک AssertionError پرتاب می‌شود.

@test.support.threading_helper.reap_threads¶: دکوراتوری برای اطمینان از پاک‌سازی نخ‌ها حتی در صورت شکست آزمون.

test.support.threading_helper.start_threads(threads, unlock=None)¶: مدیر زمینه برای شروع threads، که دنباله‌ای از نخ‌ها است. unlock تابعی است که پس از شروع نخ‌ها فراخوانی می‌شود، حتی اگر استثنایی پرتاب شده باشد؛ یک نمونه threading.Event.set() است. start_threads تلاش می‌کند نخ‌های شروع‌شده را هنگام خروج join کند.

test.support.threading_helper.threading_cleanup(*original_values)¶: پاک‌سازی نخ‌هایی که در original_values مشخص نشده‌اند. برای صدور هشدار در صورتی طراحی شده است که یک آزمون، نخ‌های در حال اجرا را در پس‌زمینه باقی بگذارد.

test.support.threading_helper.threading_setup()¶: تعداد نخ‌های فعلی و رونوشتی از نخ‌های معلق را برمی‌گرداند.

test.support.threading_helper.wait_threads_exit(timeout=None)¶: مدیر زمینه برای انتظار تا خروج همه‌ی نخ‌های ایجادشده در دستور with.

test.support.threading_helper.catch_threading_exception()¶

مدیر زمینه‌ای که استثنای threading.Thread را با استفاده از threading.excepthook() می‌گیرد.

ویژگی‌هایی که هنگام گرفته شدن یک استثنا تنظیم می‌شوند:

exc_type
exc_value
exc_traceback
thread

مستندات threading.excepthook() را ببینید.

این ویژگی‌ها در زمان خروج مدیر زمینه حذف می‌شوند.

استفاده:

with threading_helper.catch_threading_exception() as cm:
    # code spawning a thread which raises an exception
    ...

    # check the thread exception, use cm attributes:
    # exc_type, exc_value, exc_traceback, thread
    ...

# exc_type, exc_value, exc_traceback, thread attributes of cm no longer
# exists at this point
# (to avoid reference cycles)

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

test.support.threading_helper.run_concurrently(worker_func, nthreads, args=(), kwargs={})¶: تابع کارگر را به‌صورت همزمان در چندین نخ اجرا می‌کند. اگر هر نخی استثنا پرتاب کند، پس از پایان همه نخ‌ها، آن استثنا را دوباره پرتاب می‌کند.

`test.support.os_helper` --- ابزارهایی برای آزمون‌های os¶

ماژول test.support.os_helper برای آزمون‌های os پشتیبانی فراهم می‌کند.

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

test.support.os_helper.FS_NONASCII¶: یک نویسه‌ی غیر ASCII قابل کدگذاری با os.fsencode().

test.support.os_helper.SAVEDCWD¶: روی os.getcwd() تنظیم شده است.

test.support.os_helper.TESTFN¶: به نامی تنظیم شود که برای استفاده به‌عنوان نام یک پرونده موقت امن باشد. هر پرونده موقتی که ایجاد می‌شود، باید بسته و حذف (unlink) شود.

test.support.os_helper.TESTFN_NONASCII¶: به یک نام پرونده حاوی نویسه‌ی FS_NONASCII تنظیم می‌شود، اگر این نویسه وجود داشته باشد. این تضمین می‌کند که اگر نام پرونده وجود داشته باشد، می‌توان آن را با کدگذاری پیش‌فرض سامانه فایل‌بندی کدگذاری و کدگشایی کرد. این امکان را می‌دهد که آزمون‌هایی که به یک نام پرونده غیر ASCII نیاز دارند، به‌راحتی روی سکوهایی که امکان اجرای آن‌ها وجود ندارد، رد شوند.

test.support.os_helper.TESTFN_UNENCODABLE¶: به یک نام پرونده (از نوع str) تنظیم می‌شود که نباید بتوان آن را با کدگذاری سامانه فایل‌بندی در حالت سخت‌گیرانه کدگذاری کرد. اگر امکان تولید چنین نام پرونده‌ای وجود نداشته باشد، ممکن است None باشد.

test.support.os_helper.TESTFN_UNDECODABLE¶: به یک نام پرونده (نوع bytes) تنظیم شود که نباید بتوان آن را با کدگذاری سیستم پرونده در حالت سخت‌گیرانه کدگشایی کرد. اگر ایجاد چنین نام پرونده‌ای ممکن نباشد، ممکن است None باشد.

test.support.os_helper.TESTFN_UNICODE¶: روی نامی غیر ASCII برای یک پرونده موقت تنظیم شده است.

class test.support.os_helper.EnvironmentVarGuard¶: کلاسی که برای تنظیم یا لغو تنظیم موقت متغیرهای محیطی به کار می‌رود. نمونه‌ها می‌توانند به‌عنوان یک مدیر زمینه استفاده شوند و یک رابط کامل دیکشنری برای پرس‌وجو/تغییر os.environ زیربنایی دارند. پس از خروج از مدیر زمینه، تمام تغییرات اعمال‌شده بر متغیرهای محیطی از طریق این نمونه بازگردانده می‌شوند.

تغییر یافته در نسخه‌ی 3.1: رابط دیکشنری افزوده شد.

class test.support.os_helper.FakePath(path)¶: یک path-like object ساده. این شیء متد __fspath__() را پیاده‌سازی می‌کند که فقط آرگومان path را بازمی‌گرداند. اگر path یک استثنا باشد، در __fspath__() پرتاب می‌شود.

EnvironmentVarGuard.set(envvar, value)¶: به‌طور موقت متغیر محیطی envvar را به مقدار value تنظیم می‌کند.

EnvironmentVarGuard.unset(envvar, *others)¶: به‌طور موقت یک یا چند متغیر محیطی را حذف کنید.

تغییر یافته در نسخه‌ی 3.14: می‌توان بیش از یک متغیر محیطی را لغو تنظیم کرد.

test.support.os_helper.can_symlink()¶: اگر سیستم‌عامل از پیوندهای نمادین پشتیبانی کند، True و در غیر این صورت False را برمی‌گرداند.

test.support.os_helper.can_xattr()¶: اگر سیستم‌عامل از xattr پشتیبانی کند، True و در غیر این صورت False را برمی‌گرداند.

test.support.os_helper.change_cwd(path, quiet=False)¶

یک مدیر زمینه که پوشه کاری جاری را به‌طور موقت به path تغییر می‌دهد و پوشه را برمی‌گرداند.

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

test.support.os_helper.create_empty_file(filename)¶: یک پرونده خالی با filename ایجاد کنید. اگر از قبل وجود دارد، آن را کوتاه کنید .

test.support.os_helper.fd_count()¶: تعداد توصیف‌گرهای پرونده باز را بشمارید.

test.support.os_helper.fs_is_case_insensitive(directory)¶: اگر سامانه فایل‌بندی برای directory به بزرگی و کوچکی حروف حساس نباشد، True را برمی‌گرداند.

test.support.os_helper.make_bad_fd()¶: با باز کردن و بستن یک پرونده موقت و برگرداندن توصیف‌گر آن، یک توصیف‌گر پرونده نامعتبر ایجاد کنید.

test.support.os_helper.rmdir(filename)¶: os.rmdir() را روی filename فراخوانی می‌کند. در پلتفرم‌های ویندوزی، این فراخوانی با یک حلقه انتظار پوشش داده شده است که وجود پرونده را بررسی می‌کند؛ این کار به دلیل برنامه‌های ضدویروس لازم است، برنامه‌هایی که می‌توانند پرونده‌ها را باز نگه دارند و از حذف آن‌ها جلوگیری کنند.

test.support.os_helper.rmtree(path)¶: برای حذف یک مسیر و محتویات آن، shutil.rmtree() را روی path فراخوانی کنید یا os.lstat() و os.rmdir() را فراخوانی کنید. مانند rmdir()، در پلتفرم‌های ویندوز این عمل با یک حلقه انتظار که وجود پرونده‌ها را بررسی می‌کند، احاطه شده است.

@test.support.os_helper.skip_unless_symlink¶: یک دکوراتور برای اجرای آزمون‌هایی که به پشتیبانی از پیوندهای نمادین نیاز دارند.

@test.support.os_helper.skip_unless_xattr¶: دکوراتوری برای اجرای آزمون‌هایی که به پشتیبانی از xattr نیاز دارند.

test.support.os_helper.temp_cwd(name='tempcwd', quiet=False)¶

یک مدیریت‌کننده‌ی زمینه که به‌طور موقت یک پوشه‌ی جدید ایجاد می‌کند و پوشه‌ی کاری جاری (CWD) را تغییر می‌دهد.

مدیر زمینه پیش از تغییر موقت پوشه کاری جاری، یک پوشه موقت با نام name در پوشه جاری ایجاد می‌کند. اگر name برابر None باشد، پوشه موقت با استفاده از tempfile.mkdtemp() ایجاد می‌شود.

اگر quiet برابر False باشد و امکان ایجاد یا تغییر CWD وجود نداشته باشد، خطایی پرتاب می‌شود. در غیر این صورت، تنها هشداری پرتاب می‌شود و از CWD اصلی استفاده می‌شود.

test.support.os_helper.temp_dir(path=None, quiet=False)¶

یک مدیر زمینه که پوشه‌ای موقت در path ایجاد می‌کند و پوشه را برمی‌گرداند.

اگر path برابر None باشد، پوشه‌ی موقت با استفاده از tempfile.mkdtemp() ایجاد می‌شود. اگر quiet برابر False باشد، مدیر زمینه در صورت بروز خطا یک استثنا پرتاب می‌کند. در غیر این صورت، اگر path مشخص شده باشد و ایجاد آن ممکن نباشد، فقط یک هشدار نشان داده می‌شود.

test.support.os_helper.temp_umask(umask)¶: یک مدیر زمینه که به‌طور موقت umask فرایند را تنظیم می‌کند.

test.support.os_helper.unlink(filename)¶: os.unlink() را روی filename فراخوانی کنید. مانند rmdir()، در پلتفرم‌های ویندوزی، این فراخوانی با یک حلقه انتظار که وجود پرونده را بررسی می‌کند، دربرگرفته شده است.

`test.support.import_helper` --- ابزارهای کمکی برای آزمون‌های ایمپورت¶

ماژول test.support.import_helper پشتیبانی برای آزمون‌های ایمپورت را فراهم می‌کند.

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

test.support.import_helper.forget(module_name)¶: ماژول با نام module_name را از sys.modules حذف کنید و هرگونه پرونده کامپایل‌شده به بایت آن ماژول را پاک کنید.

test.support.import_helper.import_fresh_module(name, fresh=(), blocked=(), deprecated=False)¶

این تابع با حذف ماژول نام‌برده‌شده از sys.modules پیش از انجام ایمپورت، یک نسخه‌ی تازه از ماژول پایتون نام‌برده‌شده را ایمپورت می‌کند و برمی‌گرداند. توجه داشته باشید که برخلاف reload()، ماژول اصلی تحت تأثیر این عملیات قرار نمی‌گیرد.

fresh یک پیمایش‌پذیر از نام‌های ماژول اضافی است که همچنین پیش از انجام ایمپورت از نهانگاه sys.modules حذف می‌شوند.

blocked یک پیمایش‌پذیر از نام‌های ماژول است که در حین ایمپورت، در نهانگاه ماژول با None جایگزین می‌شوند تا اطمینان حاصل شود که تلاش‌ها برای ایمپورت آن‌ها باعث پرتاب ImportError می‌شوند.

ماژول نام‌برده‌شده و هر ماژولی که در پارامترهای fresh و blocked نام‌برده‌شده باشد، پیش از آغاز ایمپورت ذخیره می‌شوند و سپس هنگامی که ایمپورت تازه کامل می‌شود، دوباره در sys.modules درج می‌شوند.

اگر deprecated برابر True باشد، پیام‌های منسوخ‌شدن ماژول‌ها و بسته‌ها در جریان این ایمپورت سرکوب می‌شوند.

این تابع در صورتی که ماژول نام‌برده نتواند ایمپورت شود، ImportError را پرتاب می‌کند.

نمونه استفاده:

# Get copies of the warnings module for testing without affecting the
# version being used by the rest of the test suite. One copy uses the
# C implementation, the other is forced to use the pure Python fallback
# implementation
py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
c_warnings = import_fresh_module('warnings', fresh=['_warnings'])

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

test.support.import_helper.import_module(name, deprecated=False, *, required_on=())¶

این تابع، ماژول نام‌برده‌شده را ایمپورت کرده و برمی‌گرداند. برخلاف ایمپورت معمولی، این تابع در صورتی که ماژول نتواند ایمپورت شود، unittest.SkipTest را پرتاب می‌کند.

در صورتی که deprecated برابر True باشد، پیام‌های منسوخ‌شدگی ماژول و بسته در جریان این ایمپورت سرکوب می‌شوند. اگر ماژولی در یک پلتفرم ضروری باشد اما در پلتفرم‌های دیگر اختیاری باشد، required_on را روی یک پیمایش‌پذیر از پیشوندهای پلتفرم تنظیم کنید که با sys.platform مقایسه می‌شوند.

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

test.support.import_helper.modules_setup()¶: یک کپی از sys.modules برمی‌گرداند.

test.support.import_helper.modules_cleanup(oldmodules)¶: ماژول‌ها را به جز oldmodules و encodings حذف کنید تا نهانگاه داخلی حفظ شود.

test.support.import_helper.unload(name)¶: name را از sys.modules حذف می‌کند.

test.support.import_helper.make_legacy_pyc(source)¶: یک پرونده pyc مربوط به PEP 3147/PEP 488 را به محل pyc قدیمی آن منتقل می‌کند و مسیر سامانه فایل‌بندی‌ای برای پرونده pyc قدیمی را برمی‌گرداند. مقدار source، مسیر سامانه فایل‌بندی‌ای برای پرونده منبع است. لازم نیست پرونده منبع وجود داشته باشد، اما پرونده pyc مربوط به PEP 3147/488 باید وجود داشته باشد.

class test.support.import_helper.CleanImport(*module_names)¶

یک مدیریت‌کننده زمینه برای وادار کردن ایمپورت به بازگرداندن مرجع جدیدی از ماژول. این برای آزمایش رفتارهای سطح ماژول، مانند صدور یک DeprecationWarning هنگام ایمپورت، مفید است. نمونه کاربرد:

with CleanImport('foo'):
    importlib.import_module('foo')  # New reference.

class test.support.import_helper.DirsOnSysPath(*paths)¶

یک مدیریت‌کننده‌ی زمینه برای افزودن موقت پوشه‌ها به sys.path.

این یک رونوشت از sys.path می‌سازد، هر پوشه‌ای را که به‌عنوان آرگومان جایگاهی داده شده باشد به آن می‌افزاید، سپس هنگامی که زمینه به پایان می‌رسد، sys.path را به تنظیمات رونوشت‌شده بازمی‌گرداند.

توجه داشته باشید که تمام تغییرات sys.path در بدنه مدیر زمینه، از جمله جایگزینی شیء، در پایان بلوک به حالت پیشین بازگردانده خواهند شد.

`test.support.warnings_helper` --- ابزارهایی برای آزمون‌های هشدارها¶

ماژول test.support.warnings_helper پشتیبانی از آزمون‌های هشدارها را فراهم می‌کند.

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

test.support.warnings_helper.ignore_warnings(*, category)¶

هشدارهایی را که نمونه‌هایی از category هستند، سرکوب می‌کند؛ category باید Warning یا زیرکلاسی از آن باشد. تقریباً معادل warnings.catch_warnings() با warnings.simplefilter('ignore', category=category) است. برای مثال:

@warning_helper.ignore_warnings(category=DeprecationWarning)
def test_suppress_warning():
    # do something

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

test.support.warnings_helper.check_no_resource_warning(testcase)¶: مدیریت‌کننده‌ی زمینه برای بررسی اینکه هیچ ResourceWarning پرتاب نشده باشد. شما باید شیء‌ای را که ممکن است ResourceWarning پرتاب کند، پیش از پایان مدیریت‌کننده‌ی زمینه حذف کنید.

test.support.warnings_helper.check_syntax_warning(testcase, statement, errtext='', *, lineno=1, offset=None)¶: با تلاش برای کامپایل کردن statement، وجود هشدار سینتکسی در statement را آزمایش می‌کند. همچنین آزمایش می‌کند که SyntaxWarning تنها یک بار نشان داده می‌شود، و این که در صورت تبدیل شدن به خطا، به یک SyntaxError تبدیل خواهد شد. testcase نمونه‌ی unittest برای آزمون است. errtext عبارت باقاعده‌ای است که باید با نمایش رشته‌ای SyntaxWarning اکسپورتشده و SyntaxError پرتاب‌شده مطابقت کند. اگر lineno برابر None نباشد، با خط هشدار و استثنا مقایسه می‌شود. اگر offset برابر None نباشد، با آفست استثنا مقایسه می‌شود.

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

test.support.warnings_helper.check_warnings(*filters, quiet=True)¶

پوششی مناسب برای warnings.catch_warnings() که آزمون اینکه یک هشدار به‌درستی پرتاب شده است را آسان‌تر می‌کند. این تقریباً معادل فراخوانی warnings.catch_warnings(record=True) است، با warnings.simplefilter() که روی always تنظیم شده است و با گزینه‌ای برای اعتبارسنجی خودکار نتایجی که ثبت می‌شوند.

check_warnings تاپل‌های دوتایی به شکل ("message regexp", WarningCategory) را به‌عنوان آرگومان‌های جایگاهی می‌پذیرد. اگر یک یا چند filters ارائه شود، یا آرگومان کلیدواژه‌ای اختیاری quiet برابر False باشد، بررسی می‌کند تا اطمینان حاصل شود که هشدارها مطابق انتظار هستند: هر فیلتر مشخص‌شده باید با حداقل یکی از هشدارهای نشان داده شده توسط کد محصورشده مطابقت داشته باشد، در غیر این صورت آزمون شکست می‌خورد، و اگر هشدارهایی نشان داده شوند که با هیچ‌یک از فیلترهای مشخص‌شده مطابقت نداشته باشند، آزمون شکست می‌خورد. برای غیرفعال کردن اولین مورد از این بررسی‌ها، quiet را روی True تنظیم کنید.

اگر هیچ آرگومانی مشخص نشده باشد، به‌طور پیش‌فرض برابر است با:

check_warnings(("", Warning), quiet=True)

در این حالت، همه‌ی هشدارها گرفته می‌شوند و هیچ خطایی پرتاب نمی‌شود.

در هنگام ورود به مدیر زمینه، یک نمونه از WarningRecorder بازگردانده می‌شود. فهرست هشدارهای زیربنایی حاصل از catch_warnings() از طریق ویژگی warnings شیء ضبط‌کننده در دسترس است. برای سهولت، می‌توان به ویژگی‌های شیء نمایانگر آخرین هشدار نیز مستقیماً از طریق شیء ضبط‌کننده دسترسی پیدا کرد (مثال زیر را ببینید). اگر هیچ هشداری پرتاب نشده باشد، هر یک از ویژگی‌هایی که در حالت عادی انتظار می‌رود در شیء نمایانگر هشدار وجود داشته باشد، None را برمی‌گرداند.

شیء ضبط‌کننده همچنین یک متد reset() دارد که فهرست هشدارها را پاک می‌کند.

این مدیر زمینه به‌گونه‌ای طراحی شده است که به این شکل استفاده شود:

with check_warnings(("assertion is always true", SyntaxWarning),
                    ("", UserWarning)):
    exec('assert(False, "Hey!")')
    warnings.warn(UserWarning("Hide me!"))

در این حالت، اگر هر یک از هشدارها پرتاب نشده باشد، یا هشدار دیگری پرتاب شده باشد، check_warnings() خطایی پرتاب می‌کند.

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

with check_warnings(quiet=True) as w:
    warnings.warn("foo")
    assert str(w.args[0]) == "foo"
    warnings.warn("bar")
    assert str(w.args[0]) == "bar"
    assert str(w.warnings[0].args[0]) == "foo"
    assert str(w.warnings[1].args[0]) == "bar"
    w.reset()
    assert len(w.warnings) == 0

در اینجا تمام هشدارها گرفته خواهند شد و کد آزمون، هشدارهای گرفته‌شده را مستقیماً آزمون می‌کند.

تغییر یافته در نسخه‌ی 3.2: آرگومان‌های اختیاری جدید filters و quiet.

class test.support.warnings_helper.WarningsRecorder¶: کلاسی که برای ثبت هشدارها در آزمون واحد‌ها استفاده می‌شود. برای جزئیات بیشتر، مستندات check_warnings() در بالا را ببینید.

`test` --- بسته آزمون‌های رگرسیون برای پایتون¶

نوشتن آزمون واحد‌ها برای بسته `test`¶

اجرای آزمون‌ها با استفاده از رابط خط فرمان¶

`test.support` --- ابزارهایی برای بدنه‌ی آزمون پایتون¶

`test.support.socket_helper` --- ابزارهایی برای آزمون‌های سوکت¶

`test.support.script_helper` --- ابزارهایی برای آزمون‌های اجرای پایتون¶

`test.support.bytecode_helper` --- ابزارهای پشتیبانی برای آزمون تولید صحیح بایت‌کد¶

`test.support.threading_helper` --- ابزارهایی برای آزمون‌های نخ‌بندی¶

`test.support.os_helper` --- ابزارهایی برای آزمون‌های os¶

`test.support.import_helper` --- ابزارهای کمکی برای آزمون‌های ایمپورت¶

`test.support.warnings_helper` --- ابزارهایی برای آزمون‌های هشدارها¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

test --- بسته آزمون‌های رگرسیون برای پایتون¶

نوشتن آزمون واحد‌ها برای بسته test¶

اجرای آزمون‌ها با استفاده از رابط خط فرمان¶

test.support --- ابزارهایی برای بدنه‌ی آزمون پایتون¶

test.support.socket_helper --- ابزارهایی برای آزمون‌های سوکت¶

test.support.script_helper --- ابزارهایی برای آزمون‌های اجرای پایتون¶

test.support.bytecode_helper --- ابزارهای پشتیبانی برای آزمون تولید صحیح بایت‌کد¶

test.support.threading_helper --- ابزارهایی برای آزمون‌های نخ‌بندی¶

test.support.os_helper --- ابزارهایی برای آزمون‌های os¶

test.support.import_helper --- ابزارهای کمکی برای آزمون‌های ایمپورت¶

test.support.warnings_helper --- ابزارهایی برای آزمون‌های هشدارها¶

`test` --- بسته آزمون‌های رگرسیون برای پایتون¶

نوشتن آزمون واحد‌ها برای بسته `test`¶

`test.support` --- ابزارهایی برای بدنه‌ی آزمون پایتون¶

`test.support.socket_helper` --- ابزارهایی برای آزمون‌های سوکت¶

`test.support.script_helper` --- ابزارهایی برای آزمون‌های اجرای پایتون¶

`test.support.bytecode_helper` --- ابزارهای پشتیبانی برای آزمون تولید صحیح بایت‌کد¶

`test.support.threading_helper` --- ابزارهایی برای آزمون‌های نخ‌بندی¶

`test.support.os_helper` --- ابزارهایی برای آزمون‌های os¶

`test.support.import_helper` --- ابزارهای کمکی برای آزمون‌های ایمپورت¶

`test.support.warnings_helper` --- ابزارهایی برای آزمون‌های هشدارها¶