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

  Нове в версії 3.11.

test.support.print_warning(msg)

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

  Нове в версії 3.9.

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

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

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

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

  Нове в версії 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_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.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)

  Нове в версії 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.

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

  Нове в версії 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)

  Нове в версії 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)

  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.

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

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

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

Нове в версії 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)

  Нове в версії 3.8.

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

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

Нове в версії 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`.

test.support.os_helper.can_symlink()

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

test.support.os_helper.temp_umask(umask)

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

test.support.os_helper.unlink(filename)

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

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

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

Нове в версії 3.10.

test.support.import_helper.forget(module_name)

  Видаліть модуль із назвою module_name із `sys.modules` і видаліть усі скомпільовані файли модуля.

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

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

  Нове в версії 3.1.

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

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

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

  Нове в версії 3.1.

test.support.import_helper.modules_setup()

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

test.support.import_helper.modules_cleanup(oldmodules)

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

Нове в версії 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

  Нове в версії 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`, порівнюється зі зміщенням винятку.

  Нове в версії 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()` вище, щоб дізнатися більше.