test — Regression tests package for Python

Примітка

Пакет test призначений лише для внутрішнього використання Python. Це задокументовано на користь основних розробників Python. Будь-яке використання цього пакета поза стандартною бібліотекою Python не рекомендується, оскільки код, згаданий тут, може змінюватися або бути видалений без попередження між випусками Python.


Пакет test містить усі регресійні тести для Python, а також модулі test.support і test.regrtest. test.support використовується для вдосконалення ваших тестів, а test.regrtest керує набором тестів.

Кожен модуль у пакеті test, назва якого починається з test_, є набором тестів для певного модуля або функції. Усі нові тести слід писати за допомогою модуля unittest або doctest. Деякі старіші тести написані з використанням «традиційного» стилю тестування, який порівнює виведені дані з sys.stdout; цей стиль тесту вважається застарілим.

Дивись також

Модуль unittest

Написання регресійних тестів PyUnit.

Модуль doctest

Тести, вбудовані в рядки документації.

Написання модульних тестів для пакета test

Бажано, щоб тести, які використовують модуль unittest, дотримувалися кількох вказівок. Один із них – назвати тестовий модуль, починаючи його з test_ і закінчуючи назвою модуля, що тестується. Методи тестування в модулі тестування мають починатися з test_ і закінчуватися описом того, що метод тестує. Це потрібно для того, щоб методи розпізнавались тестовим драйвером як методи тестування. Також не слід включати рядок документації для методу. Коментар (наприклад, # Функція тестів повертає лише True або False) слід використовувати для надання документації щодо методів тестування. Це робиться тому, що рядки документації роздруковуються, якщо вони існують, і тому не вказується, який тест виконується.

Часто використовується базовий шаблон:

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 CLI, або через python -m unittest CLI.

Мета регресійного тестування — спробувати зламати код. Це призводить до кількох вказівок, яких слід дотримуватися:

  • Набір для тестування повинен використовувати всі класи, функції та константи. Це включає не лише зовнішній API, який має бути представлений зовнішньому світу, а й «приватний» код.

  • Тестування Whitebox (вивчення коду, що тестується під час написання тестів) є кращим. Тестування Blackbox (тестування лише опублікованого інтерфейсу користувача) недостатньо повне, щоб перевірити всі граничні та крайові випадки.

  • Переконайтеся, що перевірено всі можливі значення, включно з недійсними. Це гарантує, що не тільки всі дійсні значення є прийнятними, але й неправильні значення обробляються правильно.

  • Вичерпайте якомога більше шляхів коду. Перевірте, де відбувається розгалуження, і таким чином адаптуйте вхідні дані, щоб переконатися, що в коді використовується якомога більше різних шляхів.

  • Додайте явний тест для будь-яких помилок, виявлених у перевіреному коді. Це гарантує, що помилка не виникне знову, якщо код буде змінено в майбутньому.

  • Обов’язково очистіть після тестів (наприклад, закрийте та видаліть усі тимчасові файли).

  • Якщо тест залежить від конкретного стану операційної системи, то перед спробою перевірки переконайтеся, що умова вже існує.

  • Імпортуйте якомога менше модулів і робіть це якомога швидше. Це мінімізує зовнішні залежності тестів, а також мінімізує можливу аномальну поведінку через побічні ефекти імпортування модуля.

  • Спробуйте максимізувати повторне використання коду. Інколи тести відрізнятимуться дещо настільки незначним, як тип введення, що використовується. Мінімізуйте дублювання коду шляхом створення підкласу базового тестового класу з класом, який визначає вхідні дані:

    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)
    

    When using this pattern, remember that all classes that inherit from unittest.TestCase are run as tests. The TestFuncAcceptsSequencesMixin class in the example above does not have any data and so can’t be run by itself, thus it does not inherit from unittest.TestCase.

Дивись також

Розробка, орієнтована на тестування

Книга Кента Бека про написання тестів перед кодом.

Виконання тестів за допомогою інтерфейсу командного рядка

Пакет test можна запустити як сценарій для запуску набору регресійних тестів Python завдяки параметру -m: python -m test. Під капотом він використовує test.regrtest; виклик python -m test.regrtest, який використовувався в попередніх версіях Python, все ще працює. Запуск сценарію сам по собі автоматично запускає всі регресійні тести в пакеті test. Він робить це, знаходячи всі модулі в пакеті, ім’я яких починається з test_, імпортує їх і виконує функцію test_main(), якщо вона присутня, або завантажує тести через unittest.TestLoader.loadTestsFromModule, якщо test_main не існує. Назви тестів для виконання також можуть бути передані в сценарій. Якщо вказати єдиний регресійний тест (python -m test test_spam), буде мінімізовано вихідні дані та виведено лише те, чи пройдено тест чи не пройдено.

Запуск test безпосередньо дозволяє встановити, які ресурси доступні для використання тестами. Це можна зробити за допомогою параметра командного рядка -u. Якщо вказати all як значення параметра -u, усі можливі ресурси будуть активовані: python -m test -uall. Якщо потрібні всі ресурси, окрім одного (частіший випадок), список непотрібних ресурсів, розділених комами, може бути перераховано після всі. Команда python -m test -uall,-audio,-largefile запустить test з усіма ресурсами, крім ресурсів audio і largefile. Щоб отримати список усіх ресурсів і більше параметрів командного рядка, запустіть python -m test -h.

Деякі інші способи виконання регресійних тестів залежать від того, на якій платформі виконуються тести. В Unix ви можете запустити make test у каталозі верхнього рівня, де було зібрано Python. У Windows виконання rt.bat з вашого каталогу PCbuild запустить усі регресійні тести.

test.support — Утиліти для набору тестів Python

Модуль test.support забезпечує підтримку набору регресійних тестів Python.

Примітка

test.support не є публічним модулем. Це задокументовано тут, щоб допомогти розробникам Python писати тести. 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

True, якщо запущеним інтерпретатором є Jython.

test.support.is_android

True, якщо системою є Android.

test.support.unix_shell

Шлях для оболонки, якщо не в Windows; інакше Жодного.

test.support.LOOPBACK_TIMEOUT

Тайм-аут у секундах для тестів із використанням мережевого сервера, який прослуховує інтерфейс локальної петлі, як-от 127.0.0.1.

Час очікування достатньо довгий, щоб запобігти помилці тесту: він враховує, що клієнт і сервер можуть працювати в різних потоках або навіть різних процесах.

Час очікування має бути достатнім для методів connect(), recv() і send() socket. розетка.

Його значення за замовчуванням становить 5 секунд.

Дивіться також INTERNET_TIMEOUT.

test.support.INTERNET_TIMEOUT

Тайм-аут у секундах для мережевих запитів, що надходять до Інтернету.

Тайм-аут досить короткий, щоб запобігти надто довгому очікуванню тесту, якщо інтернет-запит заблоковано з будь-якої причини.

Зазвичай тайм-аут за допомогою INTERNET_TIMEOUT не повинен позначати тест як невдалий, а натомість пропускати тест: див. transient_internet().

Його значення за умовчанням становить 1 хвилину.

Дивіться також LOOPBACK_TIMEOUT.

test.support.SHORT_TIMEOUT

Тайм-аут у секундах для позначення тесту як невдалого, якщо тест триває «занадто довго».

Значення часу очікування залежить від параметра командного рядка regrtest --timeout.

Якщо тест із використанням SHORT_TIMEOUT починає випадково зазнавати помилок на повільних роботах для збірки, використовуйте натомість LONG_TIMEOUT.

Його значення за замовчуванням становить 30 секунд.

test.support.LONG_TIMEOUT

Час очікування в секундах для виявлення зависання тесту.

Його достатньо, щоб зменшити ризик невдачі тесту на найповільніших роботах для збірки Python. Його не слід використовувати для позначення тесту як невдалого, якщо тест триває «занадто довго». Значення часу очікування залежить від параметра командного рядка regrtest --timeout.

Його значення за замовчуванням становить 5 хвилин.

Дивіться також LOOPBACK_TIMEOUT, INTERNET_TIMEOUT і SHORT_TIMEOUT.

test.support.PGO

Встановіть, коли тести можна пропускати, якщо вони не корисні для PGO.

test.support.PIPE_MAX_SIZE

Константа, яка, ймовірно, більша за розмір основного буфера каналу ОС, щоб блокувати запис.

test.support.Py_DEBUG

True if Python was built with the Py_DEBUG macro defined, that is, if Python was built in debug mode.

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

Установіть значення True, якщо Python створено без рядків документації (макрос WITH_DOC_STRINGS не визначено). Перегляньте параметр configure --without-doc-strings.

Перегляньте також змінну HAVE_DOCSTRINGS.

test.support.HAVE_DOCSTRINGS

Установіть значення True, якщо доступні рядки документації функцій. Перегляньте параметр python -OO, який видаляє рядки документів функцій, реалізованих у Python.

Перегляньте також змінну 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)

Run the loop body until break stops the loop.

After timeout seconds, raise an AssertionError if error is true, or just stop the loop if error is false.

Приклад:

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

Example of error=False usage:

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)

Wait strategy that applies exponential backoff.

Run the loop body until break stops the loop. Sleep at each loop iteration, but not at the first iteration. The sleep delay is doubled at each iteration (up to max_delay seconds).

See busy_retry() documentation for the parameters usage.

Example raising an exception after SHORT_TIMEOUT seconds:

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

Example of error=False usage:

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)

Повертає True, якщо ресурс увімкнено та доступний. Список доступних ресурсів встановлюється лише тоді, коли test.regrtest виконує тести.

test.support.python_is_optimized()

Повертає True, якщо Python не було зібрано з -O0 або -Og.

test.support.with_pymalloc()

Return _testcapi.WITH_PYMALLOC.

test.support.requires(resource, msg=None)

Підніміть ResourceDenied, якщо ресурс недоступний. msg є аргументом для ResourceDenied, якщо він викликаний. Завжди повертає True, якщо викликається функцією, __name__ якої є '__main__''. Використовується, коли тести виконуються test.regrtest.

test.support.sortdict(dict)

Повертає повтор dict із відсортованими ключами.

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

Поверніть шлях до файлу з назвою filename. Якщо збігів не знайдено, повертається ім’я файлу. Це не означає помилку, оскільки це може бути шлях до файлу.

Параметр subdir вказує на відносний шлях для пошуку файлу, а не шукати безпосередньо в каталогах шляхів.

test.support.get_pagesize()

Get size of a page in bytes.

Added in version 3.12.

test.support.setswitchinterval(interval)

Установіть sys.setswitchinterval() на заданий інтервал. Визначає мінімальний інтервал для систем Android, щоб запобігти зависанню системи.

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. Він призначений для утримання стандартного виводу під час початку перевірки.

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 значення 5 протягом блоку with, відновлюючи старе значення в кінці блоку. Якщо attr не існує в obj, його буде створено, а потім видалено в кінці блоку.

Старе значення (або None, якщо воно не існує) буде призначено цільовому об’єкту «as», якщо воно є.

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

Менеджер контексту для заміни елемента новим об’єктом.

Використання:

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

Це встановить для obj["item"] значення 5 протягом блоку with, відновлюючи старе значення в кінці блоку. Якщо item не існує в obj, його буде створено, а потім видалено в кінці блоку.

Старе значення (або None, якщо воно не існує) буде призначено цільовому об’єкту «as», якщо воно є.

test.support.flush_std_streams()

Call the flush() method on sys.stdout and then on sys.stderr. It can be used to make sure that the logs order is consistent before writing into stderr.

Added in version 3.11.

test.support.print_warning(msg)

Надрукуйте попередження в sys.__stderr__. Відформатуйте повідомлення так: f"Попередження -- {msg}". Якщо повідомлення складається з кількох рядків, додайте до кожного рядка префікс «Попередження –«.

Added in version 3.9.

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

Зачекайте, поки процес pid завершиться, і переконайтеся, що код виходу процесу exitcode.

Викликати AssertionError, якщо код виходу процесу не дорівнює exitcode.

Якщо процес виконується довше timeout секунд (SHORT_TIMEOUT за замовчуванням), завершіть процес і викликайте AssertionError. Функція тайм-ауту недоступна в Windows.

Added in version 3.9.

test.support.calcobjsize(fmt)

Повертає розмір PyObject, члени структури якого визначені fmt. Повернене значення включає розмір заголовка об’єкта Python і вирівнювання.

test.support.calcvobjsize(fmt)

Повертає розмір PyVarObject, члени структури якого визначено fmt. Повернене значення включає розмір заголовка об’єкта Python і вирівнювання.

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)

Декоратор для запуску функції в іншій локалі, правильно скидаючи її після завершення. catstr — це категорія локалі у вигляді рядка (наприклад, "LC_ALL"). Передані локалі перевірятимуться послідовно, і використовуватиметься перша дійсна локаль.

@test.support.run_with_tz(tz)

Декоратор для запуску функції в певному часовому поясі, правильно скидаючи її після завершення.

@test.support.requires_freebsd_version(*min_version)

Декоратор для мінімальної версії під час виконання тесту на FreeBSD. Якщо версія FreeBSD нижча за мінімальну, тест пропускається.

@test.support.requires_linux_version(*min_version)

Декоратор для мінімальної версії під час виконання тесту в Linux. Якщо версія Linux нижча за мінімальну, тест пропускається.

@test.support.requires_mac_version(*min_version)

Декоратор для мінімальної версії під час виконання тесту на macOS. Якщо версія macOS нижча за мінімальну, тест пропускається.

@test.support.requires_gil_enabled

Decorator for skipping tests on the free-threaded build. If the GIL is disabled, the test is skipped.

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

Декоратор для пропуску тестів, якщо ресурс недоступний.

@test.support.requires_docstrings

Декоратор лише для запуску тесту, якщо HAVE_DOCSTRINGS.

@test.support.requires_limited_api

Decorator for only running the test if Limited C API is available.

@test.support.cpython_only

Декоратор для тестів, застосовний лише до CPython.

@test.support.impl_detail(msg=None, **guards)

Декоратор для виклику check_impl_detail() на guards. Якщо це повертає False, тоді використовується msg як причина для пропуску тесту.

@test.support.no_tracing

Декоратор тимчасово вимикає трасування на час тесту.

@test.support.refcount_test

Декоратор для тестів, які включають підрахунок посилань. Декоратор не запускає тест, якщо його не запускає CPython. Будь-яка функція трасування не налаштована на час тесту, щоб запобігти неочікуваним повторним підрахункам, викликаним функцією трасування.

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

Декоратор для тестів bigmem.

size — це запитуваний розмір для тесту (у довільних, інтерпретованих тестом одиницях). memuse — це кількість байтів на одиницю для тесту або її хороша оцінка. Наприклад, тест, який потребує двох байтових буферів, по 4 ГіБ кожен, можна прикрасити @bigmemtest(size=_4G, memuse=2).

Аргумент size зазвичай передається декорованому тестовому методу як додатковий аргумент. Якщо dry_run має значення True, значення, передане в метод тестування, може бути меншим за запитуване значення. Якщо dry_run має значення False, це означає, що тест не підтримує фіктивні запуски, якщо -M не вказано.

@test.support.bigaddrspacetest

Декоратор для тестів, які заповнюють адресний простір.

test.support.check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)

Перевірте синтаксичні помилки в операторі, спробувавши скомпілювати оператор. testcase — це екземпляр unittest для тесту. errtext — це регулярний вираз, який має відповідати рядковому представленню викликаної SyntaxError. Якщо lineno не є None, порівнюється з рядком винятку. Якщо offset не є None, порівнюється зі зміщенням винятку.

test.support.open_urlresource(url, *args, **kw)

Відкрийте url. Якщо відкрити не вдається, викликає TestFailed.

test.support.reap_children()

Використовуйте це в кінці test_main кожного разу, коли запускаються підпроцеси. Це допоможе гарантувати, що жодні зайві діти (зомбі) не залишаться, щоб витягнути ресурси та створювати проблеми під час пошуку рефлексів.

test.support.get_attribute(obj, name)

Отримати атрибут, викликаючи unittest.SkipTest, якщо виникає AttributeError.

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)

Added in version 3.8.

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

Загальна реалізація протоколу unittest load_tests для використання в тестових пакетах. 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.

За замовчуванням це пропускає приватні атрибути, що починаються з «_», але включає всі магічні методи, тобто ті, що починаються та закінчуються на «__».

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

Запустіть код у субінтерпретаторі. Підніміть unittest.SkipTest, якщо tracemalloc увімкнено.

test.support.check_free_after_iterating(test, iter, cls, args=())

Екземпляри Assert 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).

The extra argument can be a set of names that wouldn’t otherwise be automatically detected as «public», like objects without a proper __module__ attribute. If provided, it will be added to the automatically detected ones.

Аргумент 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)

Added in version 3.6.

test.support.skip_if_broken_multiprocessing_synchronize()

Пропустіть тести, якщо модуль multiprocessing.synchronize відсутній, якщо немає доступної реалізації семафора або якщо створення блокування викликає OSError.

Added in version 3.10.

test.support.check_disallow_instantiation(test_case, tp, *args, **kwds)

Стверджуйте, що тип tp не може бути створений за допомогою args і kwds.

Added in version 3.10.

test.support.adjust_int_max_str_digits(max_digits)

This function returns a context manager that will change the global sys.set_int_max_str_digits() setting for the duration of the context to allow execution of test code that needs a different limit on the number of digits when converting between an integer and string.

Added in version 3.11.

Модуль test.support визначає такі класи:

class test.support.SuppressCrashReport

Менеджер контексту, який використовується для запобігання діалоговим вікнам збою під час тестів, які, як очікується, призведуть до збою підпроцесу.

У Windows він вимикає діалогові вікна звітів про помилки Windows за допомогою SetErrorMode.

On UNIX, resource.setrlimit() is used to set resource.RLIMIT_CORE’s soft limit to 0 to prevent coredump file creation.

On both platforms, the old value is restored by __exit__().

class test.support.SaveSignals

Клас для збереження та відновлення обробників сигналів, зареєстрованих обробником сигналів Python.

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 забезпечує підтримку тестів сокетів.

Added in version 3.9.

test.support.socket_helper.IPV6_ENABLED

Встановіть True, якщо IPv6 увімкнено на цьому хості, 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) з портом, встановленим на 0, виявляючи невикористаний тимчасовий порт з ОС. Потім тимчасовий сокет закривається та видаляється, а тимчасовий порт повертається.

Або цей метод, або bind_port() слід використовувати для будь-яких тестів, де серверний сокет потрібно прив’язати до певного порту на час тесту. Який з них використовувати залежить від того, чи код виклику створює сокет Python, чи потрібно надати невикористаний порт у конструкторі чи передати зовнішній програмі (тобто аргумент -accept для режиму s_server openssl). Завжди віддавайте перевагу bind_port() над find_unused_port(), де це можливо. Не рекомендується використовувати жорстко закодований порт, оскільки це може зробити неможливим одночасний запуск кількох екземплярів тесту, що є проблемою для buildbots.

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

Прив’яжіть сокет до вільного порту та поверніть номер порту. Покладається на тимчасові порти, щоб переконатися, що ми використовуємо незв’язаний порт. Це важливо, оскільки багато тестів можуть виконуватися одночасно, особливо в середовищі buildbot. Цей метод викликає виняток, якщо sock.family має значення AF_INET і sock.type має значення SOCK_STREAM, і сокет має На ньому встановлено SO_REUSEADDR або SO_REUSEPORT. Тести ніколи не повинні встановлювати ці параметри сокетів для сокетів TCP/IP. Єдиним випадком встановлення цих параметрів є тестування багатоадресної розсилки через кілька сокетів UDP.

Крім того, якщо опція сокета SO_EXCLUSIVEADDRUSE доступна (тобто у Windows), вона буде встановлена на сокеті. Це не дозволить будь-кому іншому підключитися до нашого хосту/порту на час тестування.

test.support.socket_helper.bind_unix_socket(sock, addr)

Bind a Unix socket, raising unittest.SkipTest if PermissionError is raised.

@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 — Утиліти для тестів виконання Python

Модуль test.support.script_helper забезпечує підтримку тестів виконання сценаріїв Python.

test.support.script_helper.interpreter_requires_environment()

Повертає True, якщо sys.executable інтерпретатор вимагає змінних середовища, щоб взагалі мати можливість працювати.

Це призначено для використання з @unittest.skipIf() для анотування тестів, які потребують використання функції assert_python*() для запуску ізольованого режиму (-I) або без середовища процес підінтерпретатора режиму (-E).

Звичайна збірка та тестування не стикаються з такою ситуацією, але це може трапитися під час спроби запустити набір тестів стандартної бібліотеки з інтерпретатора, який не має очевидної початкової точки з поточною логікою пошуку початкової точки Python.

Налаштування 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) і повертає кортеж (код повернення, stdout, stderr).

Якщо встановлено параметр лише для ключового слова __cleanenv, env_vars використовується як нове середовище.

Python запускається в ізольованому режимі (параметр командного рядка -I), за винятком випадків, коли для параметра __isolated тільки ключове слово встановлено значення False.

Змінено в версії 3.9: Ця функція більше не видаляє пробіли з stderr.

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

Стверджуйте, що запуск інтерпретатора з args і необов’язковими змінними середовища env_vars не вдається (rc != 0), і повертайте кортеж (код повернення, stdout, stderr).

Перегляньте assert_python_ok() для отримання додаткових параметрів.

Змінено в версії 3.9: Ця функція більше не видаляє пробіли з stderr.

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

Запустіть підпроцес Python із заданими аргументами.

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 — назва архіву. Повертає кортеж, що містить (повний шлях, повний шлях до імені архіву).

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, що містить джерело. Якщо compiled має значення True, обидва вихідні файли буде скомпільовано та додано до пакета zip. Повертає кортеж повного шляху до архіву та ім’я архіву для файлу.

test.support.bytecode_helper — Інструменти підтримки для тестування правильної генерації байт-коду

Модуль test.support.bytecode_helper забезпечує підтримку для тестування та перевірки генерації байт-коду.

Added in version 3.9.

Модуль визначає наступний клас:

class test.support.bytecode_helper.BytecodeTestCase(unittest.TestCase)

У цьому класі є власні методи твердження для перевірки байт-коду.

BytecodeTestCase.get_disassembly_as_string(co)

Повернути розбирання co як рядок.

BytecodeTestCase.assertInBytecode(x, opname, argval=_UNSPECIFIED)

Повертає instr, якщо opname знайдено, інакше видає AssertionError.

BytecodeTestCase.assertNotInBytecode(x, opname, argval=_UNSPECIFIED)

Видає AssertionError, якщо знайдено opname.

test.support.threading_helper — Утиліти для потокових тестів

Модуль test.support.threading_helper забезпечує підтримку потокових тестів.

Added in version 3.10.

test.support.threading_helper.join_thread(thread, timeout=None)

Приєднайтеся до ланцюжка протягом часу очікування. Викликати AssertionError, якщо потік все ще активний після часу очікування секунд.

@test.support.threading_helper.reap_threads

Декоратор, щоб переконатися, що нитки очищені, навіть якщо тест провалиться.

test.support.threading_helper.start_threads(threads, unlock=None)

Менеджер контексту для запуску потоків, який є послідовністю потоків. unlock — це функція, яка викликається після запуску потоків, навіть якщо було викликано виняткову ситуацію; прикладом може бути threading.Event.set(). start_threads спробує приєднатися до розпочатих потоків після виходу.

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

  • потік

Перегляньте документацію 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)

Added in version 3.8.

test.support.os_helper — Утиліти для тестування ОС

Модуль test.support.os_helper забезпечує підтримку тестів ОС.

Added in version 3.10.

test.support.os_helper.FS_NONASCII

Символ не-ASCII, який можна кодувати за допомогою os.fsencode().

test.support.os_helper.SAVEDCWD

Установіть значення os.getcwd().

test.support.os_helper.TESTFN

Встановіть назву, яку можна безпечно використовувати як назву тимчасового файлу. Будь-який створений тимчасовий файл має бути закритий і від’єднаний (видалений).

test.support.os_helper.TESTFN_NONASCII

Встановіть назву файлу, яка містить символ FS_NONASCII, якщо він існує. Це гарантує, що якщо ім’я файлу існує, його можна закодувати та декодувати за допомогою стандартного кодування файлової системи. Це дозволяє легко пропускати тести, які вимагають імені файлу, відмінного від ASCII, на платформах, де вони не можуть працювати.

test.support.os_helper.TESTFN_UNENCODABLE

Встановіть ім’я файлу (тип str), яке не можна закодувати за допомогою кодування файлової системи в строгому режимі. Це може бути None, якщо неможливо згенерувати таку назву файлу.

test.support.os_helper.TESTFN_UNDECODABLE

Встановіть назву файлу (тип байтів), яку не можна буде розшифрувати за допомогою кодування файлової системи в строгому режимі. Це може бути 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)

Simple path-like object. It implements the __fspath__() method which just returns the path argument. If path is an exception, it will be raised in __fspath__().

EnvironmentVarGuard.set(envvar, value)

Тимчасово встановіть для змінної середовища envvar значення value.

EnvironmentVarGuard.unset(envvar)

Тимчасово вимкнути змінну середовища envvar.

Повертає True, якщо ОС підтримує символічні посилання, False інакше.

test.support.os_helper.can_xattr()

Повертає True, якщо ОС підтримує xattr, False інакше.

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

Менеджер контексту, який тимчасово змінює поточний робочий каталог на шлях і повертає каталог.

Якщо quiet має значення False, менеджер контексту створює виняток у разі помилки. В іншому випадку він видає лише попередження та зберігає поточний робочий каталог незмінним.

test.support.os_helper.create_empty_file(filename)

Створіть порожній файл із ім’ям. Якщо він уже існує, обріжте його.

test.support.os_helper.fd_count()

Підрахуйте кількість відкритих файлових дескрипторів.

test.support.os_helper.fs_is_case_insensitive(directory)

Повертає True, якщо файлова система для каталогу нечутлива до регістру.

test.support.os_helper.make_bad_fd()

Створіть недійсний дескриптор файлу, відкривши та закриваючи тимчасовий файл і повертаючи його дескриптор.

test.support.os_helper.rmdir(filename)

Викличте os.rmdir() на назві файлу. На платформах Windows це обернено циклом очікування, який перевіряє існування файлу, що необхідно через антивірусні програми, які можуть утримувати файли відкритими та запобігати видаленню.

test.support.os_helper.rmtree(path)

Викличте shutil.rmtree() на path або викличте os.lstat() і os.rmdir(), щоб видалити шлях і його вміст. Як і у випадку з rmdir(), на платформах Windows це обертається циклом очікування, який перевіряє існування файлів.

Декоратор для запуску тестів, які потребують підтримки символьних посилань.

@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 має значення None, тимчасовий каталог створюється за допомогою tempfile.mkdtemp(). Якщо quiet має значення False, менеджер контексту створює виняток у разі помилки. В іншому випадку, якщо вказано шлях і його неможливо створити, видається лише попередження.

test.support.os_helper.temp_umask(umask)

Менеджер контексту, який тимчасово встановлює umask процесу.

Виклик os.unlink() на назві файлу. Як і у випадку з rmdir(), на платформах Windows це обернуто циклом очікування, який перевіряє існування файлу.

test.support.import_helper — Утиліти для імпортування тестів

Модуль test.support.import_helper забезпечує підтримку тестів імпорту.

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

Ця функція імпортує та повертає нову копію названого модуля Python, видаливши названий модуль із 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'])

Added in version 3.1.

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

Ця функція імпортує та повертає названий модуль. На відміну від звичайного імпорту, ця функція викликає unittest.SkipTest, якщо модуль неможливо імпортувати.

Повідомлення про застарілі модулі та пакети пригнічуються під час цього імпорту, якщо deprecated має значення True. Якщо модуль потрібен на платформі, але необов’язковий для інших, установіть required_on на ітерацію префіксів платформи, які порівнюватимуться з sys.platform.

Added in version 3.1.

test.support.import_helper.modules_setup()

Повернути копію sys.modules.

test.support.import_helper.modules_cleanup(oldmodules)

Видаліть модулі, за винятком oldmodules і encoding, щоб зберегти внутрішній кеш.

test.support.import_helper.unload(name)

Видалити name з sys.modules.

test.support.import_helper.make_legacy_pyc(source)

Перемістіть PEP 3147/PEP 488 файл pyc до його застарілого розташування pyc і поверніть шлях файлової системи до застарілого pyc-файлу. Значення source — це шлях файлової системи до вихідного файлу. Він не обов’язково існує, однак файл PEP 3147/488 pyc має існувати.

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 забезпечує підтримку тестів попереджень.

Added in version 3.10.

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

Suppress warnings that are instances of category, which must be Warning or a subclass. Roughly equivalent to warnings.catch_warnings() with warnings.simplefilter('ignore', category=category). For example:

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

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

Перевірте синтаксичне попередження в операторі, спробувавши скомпілювати оператор. Перевірте також, що SyntaxWarning видається лише один раз, і що воно буде перетворено на SyntaxError, коли перетвориться на помилку. testcase — це екземпляр unittest для тесту. errtext — це регулярний вираз, який має відповідати рядковому представленню випущеного SyntaxWarning і викликаного SyntaxError. Якщо lineno не є None, порівнюється з рядком попередження та винятку. Якщо offset не є None, порівнюється зі зміщенням винятку.

Added in version 3.8.

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

A convenience wrapper for warnings.catch_warnings() that makes it easier to test that a warning was correctly raised. It is approximately equivalent to calling warnings.catch_warnings(record=True) with warnings.simplefilter() set to always and with the option to automatically validate the results that are recorded.

check_warnings приймає 2-кортежі форми ("message regexp", WarningCategory) як позиційні аргументи. Якщо надано один або більше фільтрів, або якщо необов’язковий аргумент ключового слова quiet має значення False, він перевіряє, щоб переконатися, що попередження відповідають очікуванням: кожен вказаний фільтр повинен відповідати принаймні одному з попереджень, викликаних вкладений код або тест не вдається, і якщо виникають попередження, які не відповідають жодному з указаних фільтрів, тест не вдається. Щоб вимкнути першу з цих перевірок, установіть quiet на True.

Якщо аргументи не вказано, за замовчуванням:

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

У цьому випадку всі попередження вловлюються, а помилки не виникають.

Після входу в контекстний менеджер повертається екземпляр WarningRecorder. Базовий список попереджень із catch_warnings() доступний через атрибут warnings об’єкта запису. Для зручності атрибути об’єкта, що представляє останнє попередження, також можна отримати безпосередньо через об’єкт запису (див. приклад нижче). Якщо попередження не було викликано, тоді будь-який з атрибутів, які в іншому випадку очікувалися б для об’єкта, що представляє попередження, поверне None.

Об’єкт recorder також має метод 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: Нові необов’язкові аргументи фільтри та тихий.

class test.support.warnings_helper.WarningsRecorder

Клас, який використовується для запису попереджень для модульних тестів. Перегляньте документацію check_warnings() вище, щоб дізнатися більше.