test — Пакет регрессионных тестов для Python

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

Каждый модуль в пакете test, имя которого начинается с test_, является набором тестов для определенного модуля или функции. Все новые тесты должны быть написаны с использованием модуля unittest или doctest. Некоторые старые тесты написаны с использованием «традиционного» стиля тестирования, который сравнивает выведенный вывод с sys.stdout; этот стиль тестирования считается устаревшим.

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

Предпочтительно, чтобы тесты, использующие модуль unittest, следовали нескольким рекомендациям. Одна из них — называть модуль тестов, начиная с test_ и заканчивая именем тестируемого модуля. Методы тестирования в модуле тестов должны начинаться с test_ и заканчиваться описанием того, что тестирует метод. Это необходимо для того, чтобы драйвер тестов распознавал методы как методы тестирования. Кроме того, не следует включать строку документации для метода. Для предоставления документации для методов тестов следует использовать комментарий (например, # Tests function returns only True or 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, или через командную строку python -m unittest.

Цель регрессионного тестирования — попытаться сломать код. Это приводит к ряду руководящих принципов:

• Набор тестов должен проверять все классы, функции и константы. Это относится не только к внешнему API, который должен быть представлен внешнему миру, но и к «приватному» коду.
• Предпочтителен белый ящик (исследование кода, который тестируется, при написании тестов). Чёрный ящик (тестирование только опубликованного пользовательского интерфейса) недостаточно полно, чтобы убедиться, что все граничные и граничные случаи протестированы.
• Убедитесь, что протестированы все возможные значения, включая недопустимые. Это гарантирует, что не только все допустимые значения приемлемы, но и то, что некорректные значения обрабатываются правильно.
• Используйте как можно больше путей кода. Тестируйте ветвления и подстраивайте ввод, чтобы пройти как можно больше разных путей по коду.
• Добавьте явный тест для любых найденных ошибок в тестируемом коде. Это обеспечит, что ошибка не возникнет снова, если код будет изменён в будущем.
• Убедитесь, что вы очищаете за собой после тестов (например, закрываете и удаляете все временные файлы).
• Если тест зависит от определённого состояния операционной системы, убедитесь, что условие уже существует, прежде чем пытаться выполнить тест.
• Импортируйте как можно меньше модулей и делайте это как можно раньше. Это сводит к минимуму внешние зависимости тестов, а также сводит к минимуму возможные аномалии поведения из-за побочных эффектов импорта модуля.

• Старайтесь максимально использовать повторное использование кода. Иногда тесты различаются даже по таким незначительным вещам, как используемый тип ввода. Минимизируйте дублирование кода, унаследовав базовый класс теста от класса, который определяет ввод:

  class TestFuncAcceptsSequencesMixin:
  
      func = mySuperWhammyFunction
  
      def test_func(self):
          self.func(self.arg)
  
  class AcceptLists(TestFuncAcceptsSequencesMixin, unittest.TestCase):
      arg = [1, 2, 3]
  
  class AcceptStrings(TestFuncAcceptsSequencesMixin, unittest.TestCase):
      arg = 'abc'
  
  class AcceptTuples(TestFuncAcceptsSequencesMixin, unittest.TestCase):
      arg = (1, 2, 3)
  

  При использовании этой структуры помните, что все классы, наследующие от unittest.TestCase, выполняются как тесты. Класс Mixin в приведённом выше примере не содержит данных, поэтому его нельзя выполнить самостоятельно, и поэтому он не наследуется от 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. Если требуется все ресурсы, кроме одного (более распространённый случай), можно перечислить через запятую ресурсы, которые не требуются, после all. Команда 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.

В этом модуле определены следующие исключения:

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

Путь к оболочке (shell), если не Windows, иначе None.

test.support.FS_NONASCII

Символ с кодом вне ASCII, который может быть закодирован функцией os.fsencode().

test.support.TESTFN

Устанавливается в безопасное имя для временного файла. Любой созданный временный файл должен быть закрыт и удалён (unlinked).

test.support.TESTFN_UNICODE

Устанавливается в имя временного файла, содержащее символы с кодами вне ASCII.

test.support.TESTFN_ENCODING

Устанавливается в значение sys.getfilesystemencoding().

test.support.TESTFN_UNENCODABLE

Устанавливается в имя файла (тип str), который не должен быть закодирован кодировкой файловой системы в строгом режиме. Может быть None, если такой файл создать невозможно.

test.support.TESTFN_UNDECODABLE

Устанавливается в имя файла (тип bytes), который не должен быть декодирован кодировкой файловой системы в строгом режиме. Может быть None, если такой файл создать невозможно.

test.support.TESTFN_NONASCII

Устанавливается в имя файла, содержащее символ FS_NONASCII.

test.support.IPV6_ENABLED

Устанавливается в True, если IPv6 включён на данном хосте, False, в противном случае.

test.support.SAVEDCWD

Устанавливается в значение os.getcwd().

test.support.PGO

Устанавливается, когда тесты можно пропустить, если они не нужны для PGO.

test.support.PIPE_MAX_SIZE

Константа, вероятно, больше, чем размер буфера канала (pipe) в ОС, для создания блокирующих операций записи.

test.support.SOCK_MAX_SIZE

Константа, вероятно, больше, чем размер буфера сокета (socket) в ОС, для создания блокирующих операций записи.

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, если выполняется на CPython, не на Windows и конфигурация не установлена с помощью WITH_DOC_STRINGS.

test.support.HAVE_DOCSTRINGS

Проверка наличия документации (docstrings).

test.support.TEST_HTTP_URL

Определяет URL специализированного HTTP-сервера для сетевых тестов.

test.support.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.

test.support.unlink(filename)

Вызывает os.unlink() для filename. На платформах Windows это обернуто циклом ожидания, который проверяет существование файла.

test.support.rmdir(filename)

Вызывает os.rmdir() для filename. На платформах Windows это обернуто циклом ожидания, который проверяет существование файла.

test.support.rmtree(path)

Вызывает shutil.rmtree() для path или вызывает os.lstat() и os.rmdir() для удаления пути и его содержимого. На платформах Windows это обернуто циклом ожидания, который проверяет существование файлов.

test.support.make_legacy_pyc(source)

Перемещает файл pyc PEP 3147/488 в его местоположение legacy pyc и возвращает путь к файлу legacy pyc. Значение source — это путь к исходному файлу. Он необязателен, однако файл pyc PEP 3147/488 должен существовать.

test.support.is_resource_enabled(resource)

Возвращает True, если ресурс resource включен и доступен. Список доступных ресурсов устанавливается только при выполнении тестов с помощью test.regrtest.

test.support.python_is_optimized()

Возвращает True, если Python не был скомпилирован с -O0 или -Og.

test.support.with_pymalloc()

Возвращает _testcapi.WITH_PYMALLOC.

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

Вызывает исключение ResourceDenied, если ресурс resource недоступен. msg — аргумент для ResourceDenied, если оно вызывается. Всегда возвращает True, если вызывается функцией, __name__ которой '__main__'. Используется при выполнении тестов с помощью test.regrtest.

test.support.system_must_validate_cert(f)

Вызывает исключение unittest.SkipTest при ошибках валидации сертификатов TLS.

test.support.sortdict(dict)

Возвращает строковое представление dict с отсортированными ключами.

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

Возвращает путь к файлу с именем filename. Если совпадение не найдено, возвращает filename. Это не означает ошибку, так как это может быть путь к файлу.
Указание subdir означает использование относительного пути для поиска файла вместо поиска непосредственно в каталогах пути.

test.support.create_empty_file(filename)

Создаёт пустой файл с именем filename. Если файл уже существует, обнуляет его.

test.support.fd_count()

Подсчитывает количество открытых дескрипторов файлов.

test.support.match_test(test)

Сопоставляет test с шаблонами, заданными в set_match_tests().

test.support.set_match_tests(patterns)

Определяет тесты сопоставления с шаблонами регулярных выражений patterns.

test.support.run_unittest(*classes)

Выполнить подклассы unittest.TestCase, переданные в функцию. Функция сканирует классы на наличие методов, начинающихся с префикса test_, и выполняет тесты индивидуально.

Также разрешается передавать строки в качестве параметров; эти строки должны быть ключами в sys.modules. Каждый связанный модуль будет просканирован функцией unittest.TestLoader.loadTestsFromModule(). Это обычно используется в следующей функции test_main():

def test_main():
    support.run_unittest(__name__)

Это выполнит все тесты, определенные в указанном модуле.

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

Выполнить doctest.testmod() для заданного модуля. Возвратить (failure_count, test_count).

Если verbosity равно None, doctest.testmod() будет выполнен с уровнем подробности, заданным значением verbose. В противном случае, он будет выполнен с уровнем подробности None. optionflags передаётся в качестве optionflags в doctest.testmod().

test.support.setswitchinterval(interval)

Установить значение sys.setswitchinterval() на заданное interval. Определяет минимальный интервал для систем Android, чтобы предотвратить зависание системы.

test.support.check_impl_detail(**guards)

Используйте эту проверку для защиты тестов CPython, специфичных для реализации, или для их выполнения только на реализациях, защищенных аргументами:

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)

Удобная оболочка для warnings.catch_warnings(), облегчающая проверку того, что предупреждение было правильно поднято. Примерно эквивалентно вызову warnings.catch_warnings(record=True) с warnings.simplefilter(), установленным в always, и с возможностью автоматической проверки полученных результатов.

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

Если не указаны аргументы, он по умолчанию:

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

В этом случае все предупреждения перехватываются, и ошибки не возникают.

При входе в контекстный менеджер возвращается экземпляр WarningRecorder. Список предупреждений из catch_warnings() доступен через атрибут warnings объекта записи. Для удобства также можно получить доступ к атрибутам объекта, представляющего последнее предупреждение, напрямую через объект записи (см. пример ниже). Если предупреждений не было, то любой из атрибутов, которые иначе ожидались бы у объекта, представляющего предупреждение, вернёт None.

Объект записи также имеет метод reset(), который очищает список предупреждений.

Контекстный менеджер предназначен для использования следующим образом:

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

В этом случае, если ни одно из предупреждений не было поднято или было поднято какое-либо другое предупреждение, check_warnings() вызовет ошибку.

Когда тесту нужно более глубоко изучить предупреждения, а не просто проверить их возникновение, можно использовать код такого вида:

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

Здесь все предупреждения будут перехвачены, а код теста непосредственно проверит перехваченные предупреждения.

Изменено в версии 3.2: Новые необязательные аргументы filters и quiet.

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. Предназначено для сохранения значения stdout на момент начала regrtest.

test.support.get_original_stdout()

Возвращает исходный stdout, установленный record_original_stdout(), или sys.stdout, если он не установлен.

test.support.strip_python_strerr(stderr)

Очистить stderr процесса Python от потенциального отладочного вывода, выводимого интерпретатором. Обычно выполняется над результатом subprocess.Popen.communicate().

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 и возвращающий директорию.

Если path равно None, временная директория создаётся с помощью tempfile.mkdtemp(). Если quiet равно False, контекстный менеджер поднимает исключение при ошибке. В противном случае, если path указан и не может быть создан, выдаётся только предупреждение.

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

Контекстный менеджер, временно изменяющий текущую рабочую директорию на path и возвращающий директорию.

Если 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.transient_internet(resource_name, *, timeout=30.0, errnos=())

Контекстный менеджер, который поднимает ResourceDenied, когда различные проблемы с подключением к интернету проявляются как исключения.

test.support.disable_faulthandler()

Контекстный менеджер, который заменяет sys.stderr на sys.__stderr__.

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

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

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

Менеджер контекста для запуска потоков. Он пытается объединить потоки при выходе.

test.support.calcobjsize(fmt)

Возвращает struct.calcsize() для nP{fmt}0n или, если gettotalrefcount существует, 2PnP{fmt}0P.

test.support.calcvobjsize(fmt)

Возвращает struct.calcsize() для nPn{fmt}0n или, если gettotalrefcount существует, 2PnPn{fmt}0P.

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

Для тестового случая test, утверждается, что размер sys.getsizeof для o плюс размер заголовка сборки мусора равен size.

test.support.can_symlink()

Возвращает True если операционная система поддерживает символические ссылки, False в противном случае.

test.support.can_xattr()

Возвращает True если ОС поддерживает xattr, False в противном случае.

@test.support.skip_unless_symlink

Декоратор для запуска тестов, которые требуют поддержки символических ссылок.

@test.support.skip_unless_xattr

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

@test.support.skip_unless_bind_unix_socket

Декоратор для запуска тестов, которые требуют функционального bind() для Unix-сокет.

@test.support.anticipate_failure(condition)

Декоратор для условной маркировки тестов с unittest.expectedFailure(). Любое использование этого декоратора должно иметь связанный комментарий, идентифицирующий соответствующую проблему в трекере.

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

Декоратор для запуска функции в другом локали, правильно сбрасывая его после завершения. catstr - категория локали в виде строки (например, "LC_ALL"). Переданные locales будут пробоваться последовательно, и первая допустимая локаль будет использована.

@test.support.run_with_tz(tz)

Декоратор для запуска функции в определённом часовом поясе, правильно сбрасывая его после завершения.

@test.support.requires_freebsd_version(*min_version)

Декоратор для минимальной версии при выполнении теста на FreeBSD. Если версия FreeBSD меньше минимальной, вызывается unittest.SkipTest.

@test.support.requires_linux_version(*min_version)

Декоратор для минимальной версии при выполнении теста на Linux. Если версия Linux меньше минимальной, вызывается unittest.SkipTest.

@test.support.requires_mac_version(*min_version)

Декоратор для минимальной версии при выполнении теста на Mac OS X. Если версия Mac OS X меньше минимальной, вызывается 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)

Декоратор для пропуска тестов, если модуль 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)

Декоратор для тестов с большими объемами памяти.

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

Аргумент size обычно передаётся в декорированный тестовый метод как дополнительный аргумент. Если dry_run True, значение, переданное тестовому методу, может быть меньше запрошенного значения. Если dry_run False, это означает, что тест не поддерживает пробные запуски, когда -M не указано.

@test.support.bigaddrspacetest(f)

Декоратор для тестов, заполняющих адресное пространство. f - функция для обертывания.

test.support.make_bad_fd()

Создаёт недействительный дескриптор файла путём открытия и закрытия временного файла и возвращает его дескриптор.

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

Проверка синтаксических ошибок в statement путём попытки компиляции statement. testcase - экземпляр unittest для теста. errtext - текст ошибки, поднятой SyntaxError. Если lineno не равно None, сравнивает с строкой SyntaxError. Если offset не равно None, сравнивает со смещением SyntaxError.

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 и encodings, для сохранения внутреннего кэша.

test.support.threading_setup()

Возвращает текущее количество потоков и копию зависших потоков.

test.support.threading_cleanup(*original_values)

Очищает потоки, не указанные в original_values. Предназначена для выдачи предупреждения, если тест оставляет работающие потоки в фоновом режиме.

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

Объединяет thread в течение timeout. Вызывает AssertionError, если поток по-прежнему активен после timeout секунд.

test.support.reap_children()

Используйте эту функцию в конце test_main, когда запускаются дочерние процессы. Это поможет гарантировать, что дополнительные дочерние (зомби) процессы не останутся, чтобы занимать ресурсы и создавать проблемы при поиске утечек памяти.

test.support.get_attribute(obj, name)

Получает атрибут, вызывая unittest.SkipTest, если возникает AttributeError.

test.support.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.bind_unix_socket(sock, addr)

Связывает UNIX-сокет, вызывая unittest.SkipTest, если возникает PermissionError.

test.support.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() по возможности. Использование жёстко заданного порта не рекомендуется, так как это может сделать невозможным одновременный запуск нескольких экземпляров теста, что является проблемой для buildbot.

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, если файловая система для directory нечувствительна к регистру.

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

Возвращает набор атрибутов, функций или методов ref_api, отсутствующих в other_api, за исключением определённого списка элементов, которые необходимо игнорировать в этом проверке, указанного в ignore.

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

Добавлена в версии 3.5.

test.support.patch(test_instance, object_to_patch, attr_name, new_value)

Переопределяет object_to_patch.attr_name с помощью new_value. Также добавляет процедуру очистки в test_instance для восстановления object_to_patch для attr_name. attr_name должен быть допустимым атрибутом для object_to_patch.

test.support.run_in_subinterp(code)

Выполняет code в подинтерпретаторе. Вызывает unittest.SkipTest, если tracemalloc включён.

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

Проверяет, что iter освобождается после итерирования.

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

Аргумент extra может быть набором имён, которые в противном случае не были бы автоматически распознаны как «публичные», например, объекты без соответствующего атрибута __module__. Если он указан, он будет добавлен к автоматически распознанным.

Аргумент blacklist может быть множеством имён, которые не должны рассматриваться как часть публичного 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'}
        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 определяет следующие классы:

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

Экземпляры являются менеджером контекста, который поднимает ResourceDenied, если указанный тип исключения поднят. Любые ключевые аргументы рассматриваются как пары атрибут/значение, которые сравниваются с любым исключением, поднятым в блоке with. Только если все пары правильно соответствуют атрибутам исключения, поднимается ResourceDenied.

class test.support.EnvironmentVarGuard

Класс, используемый для временного задания или отмены переменных окружения. Экземпляры могут использоваться как менеджер контекста и имеют полный интерфейс словаря для запросов/модификаций базового os.environ. После выхода из менеджера контекста все изменения переменных окружения, выполненные через этот экземпляр, будут отменены.

Изменено в версии 3.1: Добавлен интерфейс словаря.

EnvironmentVarGuard.set(envvar, value)

Временно задаёт переменную окружения envvar значением value.

EnvironmentVarGuard.unset(envvar)

Временно отменяет переменную окружения envvar.

class test.support.SuppressCrashReport

Менеджер контекста, используемый для предотвращения всплывающих окон сообщений об ошибках при тестах, ожидающих сбоя подпроцесса.

В Windows он отключает диалоговые окна Windows Error Reporting с помощью SetErrorMode.

В UNIX используется resource.setrlimit() для установки мягкого ограничения resource.RLIMIT_CORE в 0, чтобы предотвратить создание файла coredump.

На обеих платформах старое значение восстанавливается с помощью __exit__().

class test.support.CleanImport(*module_names)

Менеджер контекста, принудительно возвращающий новую ссылку на модуль при импорте. Это полезно для тестирования поведения на уровне модулей, такого как выдача DeprecationWarning при импорте. Пример использования:

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

class test.support.DirsOnSysPath(*paths)

Менеджер контекста для временного добавления каталогов в 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)

Выполнить тест и вернуть результат.

class test.support.TestHandler(logging.handlers.BufferingHandler)

Класс для поддержки журналирования.

class test.support.FakePath(path)

Простой объект, подобный пути. Он реализует метод __fspath__(), который просто возвращает аргумент path. Если path является исключением, оно будет поднято в __fspath__().

test.support.script_helper — Утилиты для тестов выполнения скриптов Python

Модуль test.support.script_helper предоставляет поддержку для тестов выполнения скриптов Python.

test.support.script_helper.interpreter_requires_environment()

Возвращает True, если sys.executable interpreter требует переменных среды для выполнения.

Это предназначено для использования с @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.

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

Проверяет, что запуск интерпретатора с args и необязательными переменными среды env_vars завершается успешно (rc == 0) и возвращает кортеж (return code, stdout, stderr).

Если ключевое слово __cleanenv установлено, env_vars используется как новая среда.

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

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

Проверяет, что запуск интерпретатора с args и необязательными переменными среды env_vars завершается ошибкой (rc != 0) и возвращает кортеж (return code, stdout, stderr).

См. assert_python_ok() для получения дополнительных параметров.

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 — имя в архиве. Вернуть кортеж, содержащий (full path, full path of archive name).

test.support.script_helper.make_pkg(pkg_dir, init_source='')

Создать каталог с именем pkg_dir, содержащий файл __init__, содержащий init_source в качестве содержимого.

test.support.script_helper.make_zip_pkg(zip_dir, zip_basename, pkg_name, script_basename, source, depth=1, compiled=False)

Создать zip-пакет в каталоге с путем zip_dir и zip_basename, содержащий пустой файл __init__ и файл script_basename, содержащий source. Если compiled равно True, оба исходных файла будут скомпилированы и добавлены в zip-пакет. Вернуть кортеж полного пути zip-файла и имени в архиве для zip-файла.