Учебники

UnitTest Framework — API Doctest

Август 17, 2018

API doctest вращается вокруг следующих двух контейнерных классов, используемых для хранения интерактивных примеров из строк документации:

  • Пример — один оператор Python в сочетании с ожидаемым результатом.

  • DocTest — коллекция примеров, обычно извлекаемая из одной строки документации или текстового файла.

Пример — один оператор Python в сочетании с ожидаемым результатом.

DocTest — коллекция примеров, обычно извлекаемая из одной строки документации или текстового файла.

Следующие дополнительные классы обработки определены для поиска, анализа, запуска и проверки примеров doctest —

  • DocTestFinder — Находит все строки документации в данном модуле и использует DocTestParser для создания DocTest из каждой строки документации, содержащей интерактивные примеры.

  • DocTestParser — Создает объект doctest из строки (такой как строка документа объекта).

  • DocTestRunner — выполняет примеры в тестовом документе и использует OutputChecker для проверки их вывода.

  • OutputChecker — сравнивает фактический вывод из примера doctest с ожидаемым выводом и решает, соответствуют ли они.

DocTestFinder — Находит все строки документации в данном модуле и использует DocTestParser для создания DocTest из каждой строки документации, содержащей интерактивные примеры.

DocTestParser — Создает объект doctest из строки (такой как строка документа объекта).

DocTestRunner — выполняет примеры в тестовом документе и использует OutputChecker для проверки их вывода.

OutputChecker — сравнивает фактический вывод из примера doctest с ожидаемым выводом и решает, соответствуют ли они.

Класс DocTestFinder

Это класс обработки, используемый для извлечения тестовых документов, которые имеют отношение к данному объекту, из его строки документации и строк документации содержащихся в ней объектов. В настоящее время Doctests может быть извлечена из следующих типов объектов — модулей, функций, классов, методов, статических методов, методов классов и свойств.

Этот класс определяет метод find (). Он возвращает список DocTests, которые определены строкой документации объекта или любой из строк документации содержащихся в нем объектов.

Класс DocTestParser

Это класс обработки, используемый для извлечения интерактивных примеров из строки и использования их для создания объекта DocTest. Этот класс определяет следующие методы —

  • get_doctest () — извлекает все примеры doctest из заданной строки и собирает их в объект DocTest .

  • get_examples (string [, name]) — извлекает все примеры doctest из заданной строки и возвращает их в виде списка объектов Example . Номера строк начинаются с 0. Необязательный аргумент name является именем, идентифицирующим эту строку, и используется только для сообщений об ошибках.

  • parse (string [, name]) — Разделите данную строку на примеры и промежуточный текст и верните их в виде списка чередующихся примеров и строк. Номера строк для примеров начинаются с 0. Необязательный аргумент name является именем, идентифицирующим эту строку, и используется только для сообщений об ошибках.

get_doctest () — извлекает все примеры doctest из заданной строки и собирает их в объект DocTest .

get_examples (string [, name]) — извлекает все примеры doctest из заданной строки и возвращает их в виде списка объектов Example . Номера строк начинаются с 0. Необязательный аргумент name является именем, идентифицирующим эту строку, и используется только для сообщений об ошибках.

parse (string [, name]) — Разделите данную строку на примеры и промежуточный текст и верните их в виде списка чередующихся примеров и строк. Номера строк для примеров начинаются с 0. Необязательный аргумент name является именем, идентифицирующим эту строку, и используется только для сообщений об ошибках.

DocTestRunner Class

Это класс обработки, используемый для выполнения и проверки интерактивных примеров в DocTest. В нем определены следующие методы —

report_start ()

Сообщите, что организатор теста собирается обработать данный пример. Этот метод предоставлен, чтобы позволить подклассам DocTestRunner настраивать их вывод; он не должен вызываться напрямую

report_success ()

Сообщите, что приведенный пример успешно выполнен. Этот метод предоставлен, чтобы позволить подклассам DocTestRunner настраивать их вывод; это не должно быть вызвано напрямую.

report_failure ()

Сообщите, что приведенный пример не удался. Этот метод предоставлен, чтобы позволить подклассам DocTestRunner настраивать их вывод; это не должно быть вызвано напрямую.

report_unexpected_exception ()

Сообщите, что данный пример вызвал неожиданное исключение. Этот метод предоставлен, чтобы позволить подклассам DocTestRunner настраивать их вывод; это не должно быть вызвано напрямую.

бег (тест)

Запустите тестируемые примеры (объект DocTest) и отобразите результаты, используя функцию записи.

Подводя итог ([многословный])

Распечатайте сводку всех тестовых случаев, которые были выполнены этим DocTestRunner, и верните именованный кортеж TestResults (не удалось, попытка). Необязательный подробный аргумент контролирует, насколько детализирована сводка. Если многословие не указано, то используется многословие DocTestRunner.

Класс OutputChecker

Этот класс используется, чтобы проверить, соответствует ли фактический вывод из примера документа ожидаемому результату.

Следующие методы определены в этом классе —

check_output ()

Верните True, если фактический результат из примера ( полученный ) совпадает с ожидаемым результатом ( хотите ). Эти строки всегда считаются совпадающими, если они идентичны; но в зависимости от того, какие флажки использует тестовый исполнитель, также возможны несколько типов неточного совпадения. Смотрите раздел Флаги параметров и Директивы для получения дополнительной информации о флагах параметров.

output_difference ()

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

Интеграция DocTest с Unittest

Модуль doctest предоставляет две функции, которые можно использовать для создания тестовых комплектов unittest из модулей и текстовых файлов, содержащих doctests. Для интеграции с обнаружением тестов unittest включите функцию load_tests () в ваш тестовый модуль — 

import unittest
import doctest
import doctestexample

def load_tests(loader, tests, ignore):
   tests.addTests(doctest.DocTestSuite(doctestexample))
   return tests

Будет сформирован комбинированный TestSuite тестов из unittest и doctest, и теперь он может быть выполнен методом main () модуля unittest или методом run ().

Ниже приведены две основные функции для создания экземпляров unittest.TestSuite из текстовых файлов и модулей с doctests —

doctest.DocFileSuite ()

Он используется для преобразования тестов doctest из одного или нескольких текстовых файлов в unittest.TestSuite . Возвращенный unittest.TestSuite должен быть запущен платформой unittest и запускает интерактивные примеры в каждом файле. Если какой-либо из примеров в файле дает сбой, то синтезированный модульный тест завершается неудачей, и возникает исключение errorException, показывающее имя файла, содержащего тест, и (иногда приблизительный) номер строки.

doctest.DocTestSuite ()

Он используется для преобразования тестов doctest для модуля в unittest.TestSuite .

Возвращенный unittest.TestSuite должен быть запущен платформой unittest и выполняет каждый doctest в модуле. Если какой-либо из тестов не пройден, то синтезированный модульный тест не пройден , и генерируется исключение failException, показывающее имя файла, содержащего тест, и (иногда приблизительный) номер строки

Под прикрытием DocTestSuite () создает unittest.TestSuite из экземпляров doctest.DocTestCase, а DocTestCase является подклассом unittest.TestCase.

Аналогичным образом DocFileSuite () создает unittest.TestSuite из экземпляров doctest.DocFileCase, а DocFileCase является подклассом DocTestCase.

Таким образом, оба способа создания unittest.TestSuite запускают экземпляры DocTestCase. Когда вы сами запускаете функции doctest, вы можете напрямую управлять используемыми параметрами doctest, передавая флаги параметров функциям doctest.

Однако, если вы пишете инфраструктуру unittest, unittest, в конечном счете, контролирует, когда и как запускаются тесты. Автор платформы обычно хочет управлять параметрами отчетов doctest (возможно, например, указанными в параметрах командной строки), но нет способа передать опции через unittest участникам тестов doctest.

38
Share: