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

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

test.support.TESTFN

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

test.support.TESTFN_UNICODE

Встановіть назву, відмінну від ASCII, для тимчасового файлу.

test.support.TESTFN_ENCODING

Set to sys.getfilesystemencoding().

test.support.TESTFN_UNENCODABLE

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

test.support.TESTFN_UNDECODABLE

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

test.support.TESTFN_NONASCII

Set to a filename containing the FS_NONASCII character.

test.support.LOOPBACK_TIMEOUT

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

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

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

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

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

test.support.INTERNET_TIMEOUT

Timeout in seconds for network requests going to the Internet.

The timeout is short enough to prevent a test to wait for too long if the Internet request is blocked for whatever reason.

Зазвичай тайм-аут за допомогою 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.SAVEDCWD

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

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

Return True if running on CPython, not on Windows, and configuration not set with WITH_DOC_STRINGS.

test.support.HAVE_DOCSTRINGS

Check for presence of 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.forget(module_name)

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

test.support.unload(name)

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

Call os.unlink() on filename. On Windows platforms, this is wrapped with a wait loop that checks for the existence of the file.

test.support.rmdir(filename)

Call os.rmdir() on filename. On Windows platforms, this is wrapped with a wait loop that checks for the existence of the file.

test.support.rmtree(path)

Call shutil.rmtree() on path or call os.lstat() and os.rmdir() to remove a path and its contents. On Windows platforms, this is wrapped with a wait loop that checks for the existence of the files.

test.support.make_legacy_pyc(source)

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

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.system_must_validate_cert(f)

Raise unittest.SkipTest on TLS certification validation failures.

test.support.sortdict(dict)

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

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

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

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

test.support.create_empty_file(filename)

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

test.support.fd_count()

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

test.support.match_test(test)

Match test to patterns set in set_match_tests().

test.support.set_match_tests(patterns)

Define match test with regular expression patterns.

test.support.run_unittest(*classes)

Execute unittest.TestCase subclasses passed to the function. The function scans the classes for methods starting with the prefix test_ and executes the tests individually.

It is also legal to pass strings as parameters; these should be keys in sys.modules. Each associated module will be scanned by unittest.TestLoader.loadTestsFromModule(). This is usually seen in the following test_main() function:

def test_main():
    support.run_unittest(__name__)

This will run all tests defined in the named module.

test.support.run_doctest(module, verbosity=None, optionflags=0)

Run doctest.testmod() on the given module. Return (failure_count, test_count).

If verbosity is None, doctest.testmod() is run with verbosity set to verbose. Otherwise, it is run with verbosity set to None. optionflags is passed as optionflags to doctest.testmod().

test.support.setswitchinterval(interval)

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

test.support.check_impl_detail(**guards)

Use this check to guard CPython’s implementation-specific tests or to run them only on the implementations guarded by the arguments:

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

test.support.check_no_resource_warning(testcase)

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

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.temp_dir(path=None, quiet=False)

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

Якщо path має значення None, тимчасовий каталог створюється за допомогою tempfile.mkdtemp(). Якщо quiet має значення False, менеджер контексту створює виняток у разі помилки. В іншому випадку, якщо вказано шлях і його неможливо створити, видається лише попередження.

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

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

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

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

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

Менеджер контексту створює тимчасовий каталог у поточному каталозі з назвою name перед тим, як тимчасово змінити поточний робочий каталог. Якщо name має значення None, тимчасовий каталог створюється за допомогою tempfile.mkdtemp().

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

test.support.temp_umask(umask)

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

test.support.disable_faulthandler()

A context manager that replaces sys.stderr with sys.__stderr__.

test.support.gc_collect()

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

test.support.disable_gc()

A context manager that disables the garbage collector upon entry and reenables it upon exit.

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.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.wait_threads_exit(timeout=60.0)

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

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

Context manager to start threads. It attempts to join the threads upon exit.

test.support.calcobjsize(fmt)

Return struct.calcsize() for nP{fmt}0n or, if gettotalrefcount exists, 2PnP{fmt}0P.

test.support.calcvobjsize(fmt)

Return struct.calcsize() for nPn{fmt}0n or, if gettotalrefcount exists, 2PnPn{fmt}0P.

test.support.checksizeof(test, o, size)

Для тестового випадку test переконайтеся, що sys.getsizeof для o плюс розмір заголовка GC дорівнює size.

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

test.support.can_xattr()

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

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

@test.support.skip_unless_xattr

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

@test.support.anticipate_failure(condition)

Декоратор для умовного позначення тестів unittest.expectedFailure(). Будь-яке використання цього декоратора повинно мати відповідний коментар, що визначає відповідну проблему трекера.

@test.support.run_with_locale(catstr, *locales)

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

@test.support.run_with_tz(tz)

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

@test.support.requires_freebsd_version(*min_version)

Decorator for the minimum version when running test on FreeBSD. If the FreeBSD version is less than the minimum, raise unittest.SkipTest.

@test.support.requires_linux_version(*min_version)

Decorator for the minimum version when running test on Linux. If the Linux version is less than the minimum, raise unittest.SkipTest.

@test.support.requires_mac_version(*min_version)

Decorator for the minimum version when running test on macOS. If the macOS version is less than the minimum, raise unittest.SkipTest.

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

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

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

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

@test.support.no_tracing(func)

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

@test.support.refcount_test(test)

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

@test.support.reap_threads(func)

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

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

Decorator for tests that fill the address space. f is the function to wrap.

test.support.make_bad_fd()

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

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

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

test.support.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.open_urlresource(url, *args, **kw)

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

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

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

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

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

test.support.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.modules_setup()

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

test.support.modules_cleanup(oldmodules)

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

test.support.threading_setup()

Повертає поточну кількість потоків і копію завислих потоків.

test.support.threading_cleanup(*original_values)

Очистити потоки, не вказані в original_values. Призначений для видачі попередження, якщо тест залишає запущені потоки у фоновому режимі.

test.support.join_thread(thread, timeout=30.0)

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

test.support.reap_children()

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

test.support.get_attribute(obj, name)

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

test.support.catch_threading_exception()

Менеджер контексту перехоплює виняток threading.Thread за допомогою threading.excepthook().

Атрибути, які встановлюються, коли виявляється виняток:

  • exc_type

  • exc_value

  • exc_traceback

  • потік

Перегляньте документацію threading.excepthook().

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

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

with support.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.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.fs_is_case_insensitive(directory)

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

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 that iter is deallocated after iterating.

test.support.missing_compiler_executable(cmd_names=[])

Перевірте наявність виконуваних файлів компілятора, імена яких указано в cmd_names, або всіх виконуваних файлів компілятора, якщо cmd_names порожній, і поверніть перший відсутній виконуваний файл або None, якщо жоден відсутній.

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

Переконайтеся, що змінна __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.

The blacklist argument can be a set of names that must not be treated as part of the public API even though their names indicate otherwise.

Приклад використання:

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'}
        blacklist = {'baz'}  # Undocumented name.
        # bar imports part of its API from _bar.
        support.check__all__(self, bar, ('bar', '_bar'),
                             extra=extra, blacklist=blacklist)

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

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

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

class test.support.TransientResource(exc, **kwargs)

Instances are a context manager that raises ResourceDenied if the specified exception type is raised. Any keyword arguments are treated as attribute/value pairs to be compared against any exception raised within the with statement. Only if all pairs match properly against attributes on the exception is ResourceDenied raised.

class test.support.EnvironmentVarGuard

Клас, який використовується для тимчасового встановлення або вимкнення змінних середовища. Екземпляри можна використовувати як контекстний менеджер і мати повний інтерфейс словника для запитів/модифікації основного os.environ. Після виходу з диспетчера контексту всі зміни змінних середовища, внесені через цей екземпляр, буде відкочено.

Змінено в версії 3.1: Додано інтерфейс словника.

EnvironmentVarGuard.set(envvar, value)

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

EnvironmentVarGuard.unset(envvar)

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

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.CleanImport(*module_names)

A context manager to force import to return a new module reference. This is useful for testing module-level behaviors, such as the emission of a DeprecationWarning on import. Example usage:

with CleanImport('foo'):
    importlib.import_module('foo')  # New reference.
class test.support.DirsOnSysPath(*paths)

A context manager to temporarily add directories to sys.path.

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

Зауважте, що всі sys.path зміни в тілі контекстного менеджера, включаючи заміну об’єкта, буде скасовано в кінці блоку.

class test.support.SaveSignals

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

class test.support.Matcher
matches(self, d, **kwargs)

Спробуйте зіставити один диктовок із наданими аргументами.

match_value(self, k, dv, v)

Спробуйте зіставити одне збережене значення (dv) із наданим значенням (v).

class test.support.WarningsRecorder

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

class test.support.BasicTestRunner
run(test)

Run test and return the result.

class test.support.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__().

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

If the __cleanenv keyword is set, env_vars is used as a fresh environment.

Python is started in isolated mode (command line option -I), except if the __isolated keyword is set to 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.