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

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

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

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.support --- ابزارهایی برای بدنه‌ی آزمون پایتون¶

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

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

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 به‌اندازه کافی طولانی باشد.

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

همچنین 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()¶

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

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

این را از setUp()، tearDown()، یا tearDownModule() در آزمون‌هایی که زیرفرایندها را شروع می‌کنند، فراخوانی کنید. این کار کمک می‌کند اطمینان حاصل شود که هیچ فرزند اضافی (زامبی) باقی نمی‌ماند تا منابع را ببلعد و هنگام جستجوی نشتی‌های مرجع (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 دنباله‌ای از گزینه‌های خط فرمان مفسر برای اجرای زیرفرایند است، و env نگاشتی از متغیرهای محیطی برای تنظیم در آن، بر روی محیط ارث‌برده است. مقدار None در env متغیر را حذف می‌کند. توجه داشته باشید که -E و -I باعث می‌شوند زیرفرایند متغیرهای محیطی PYTHON* را نادیده بگیرد، از جمله PYTHONPATH.

timeout تعداد ثانیه‌های انتظار برای زیرفرایند است؛ اگر در وقت تمام نشود، آزمون به عنوان خطا گزارش می‌شود. به طور پیش‌فرض مهلت زمانی وجود ندارد، و یک آزمون معلق به مهلت زمانیِ اجرای آزمون واگذار می‌شود.

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

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 یا PYTHONNOUSERSITE دیگر متغیرهای محیطی رایجی هستند که ممکن است روی توانایی مفسر در شروع به کار تأثیر بگذارند.

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

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

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) را فراهم می‌کند.

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 پشتیبانی فراهم می‌کند.

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.os_helper.with_source_date_epoch(*, epoch=123456789)¶

یک آراینده برای اجرای آزمون‌ها با متغیر محیطی SOURCE_DATE_EPOCH که روی epoch تنظیم شده است.

@test.support.os_helper.without_source_date_epoch¶

یک آراینده برای اجرای آزمون‌ها در حالی که متغیر محیطی SOURCE_DATE_EPOCH تنظیم نشده است.

class test.support.os_helper.SourceDateEpochTestMeta¶

فراکلاسی که تمام متدهای آزمون کلاس را با with_source_date_epoch() احاطه می‌کند، اگر آرگومان کلیدواژه‌ای کلاس source_date_epoch برابر با True باشد، و در غیر این صورت با without_source_date_epoch(). برای مثال:

class TestsWithSourceEpoch(Tests,
                           metaclass=SourceDateEpochTestMeta,
                           source_date_epoch=True):
    pass

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

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

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

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

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)

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

هنگام ورود به مدیر زمینه، یک نمونه از WarningsRecorder برگردانده می‌شود. هشدارهای ضبط‌شده از طریق ویژگی warnings آن در دسترس هستند و متد 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.message) == "foo"
    warnings.warn("bar")
    assert str(w.message) == "bar"
    assert str(w.warnings[0].message) == "foo"
    assert str(w.warnings[1].message) == "bar"
    w.reset()
    assert len(w.warnings) == 0

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

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

class test.support.warnings_helper.WarningsRecorder(warnings_list)¶

کلاسی که برای ثبت هشدارها برای آزمون‌های واحد استفاده می‌شود. هنگامی که ثبت هشدار فعال است، فهرست هشدارهای برگردانده‌شده توسط warnings.catch_warnings() را دربرمی‌گیرد. تابع check_warnings() نمونه‌ای از این کلاس را برمی‌گرداند.

به عنوان یک امکان رفاهی، ویژگی‌های شیء نماینده‌ی جدیدترین هشدار را نیز می‌توان مستقیماً از طریق شیء ثبت‌کننده (recorder) دسترسی داشت. اگر از زمان ایجاد یا آخرین بازنشانی ثبت‌کننده هیچ هشداری صادر نشده باشد، این ویژگی‌ها مقدار None را برمی‌گردانند.

warnings¶

فهرستی از هشدارهای ثبت‌شده از زمان ایجاد یا آخرین بازنشانی ثبت‌کننده.

reset()¶

هشدار‌های ضبط‌شده‌ی قبلی را از نمای (view) recorder حذف کنید. فهرست (list) هشدار‌های زیرین تغییر نمی‌کند.