UnitTest Framework - Doctest API
API doctest вращается вокруг следующих двух классов-контейнеров, используемых для хранения интерактивных примеров из строк документации:
Example - Один оператор Python в паре с ожидаемым результатом.
DocTest - Коллекция примеров, обычно извлекаемых из одной строки документации или текстового файла.
Следующие дополнительные классы обработки определены для поиска, анализа, запуска и проверки примеров документации:
DocTestFinder - Находит все строки документации в данном модуле и использует DocTestParser для создания DocTest из каждой строки документации, содержащей интерактивные примеры.
DocTestParser - Создает объект doctest из строки (например, строки документации объекта).
DocTestRunner - Выполняет примеры в doctest и использует OutputChecker для проверки их вывода.
OutputChecker - Сравнивает фактический результат теста doctest с ожидаемым результатом и решает, совпадают ли они.
DocTestFinder Класс
Это класс обработки, используемый для извлечения тестов документации, относящихся к данному объекту, из его строки документации и строк документации содержащихся в нем объектов. Доктесты в настоящее время могут быть извлечены из следующих типов объектов - модулей, функций, классов, методов, статических методов, методов классов и свойств.
Этот класс определяет метод find (). Он возвращает список тестов DocTests, которые определены строкой документации объекта или строками документации любого из содержащихся в нем объектов.
DocTestParser Класс
Это класс обработки, используемый для извлечения интерактивных примеров из строки и использования их для создания объекта DocTest. Этот класс определяет следующие методы -
get_doctest() - Извлеките все примеры тестов из заданной строки и соберите их в DocTest объект.
get_examples(string[, name]) - Извлечь все примеры тестов из заданной строки и вернуть их в виде списка Exampleобъекты. Номера строк начинаются с 0. Необязательное имя аргумента - это имя, идентифицирующее эту строку, и используется только для сообщений об ошибках.
parse(string[, name]) - Разделите данную строку на примеры и промежуточный текст и верните их как список чередующихся Examplesи струны. Номера строк дляExamplesначинаются с 0. Необязательное имя аргумента - это имя, идентифицирующее эту строку, и используется только для сообщений об ошибках.
DocTestRunner Класс
Это класс обработки, используемый для выполнения и проверки интерактивных примеров в DocTest. В нем определены следующие методы -
report_start ()
Сообщите, что средство запуска тестов собирается обработать данный пример. Этот метод позволяет подклассамDocTestRunnerнастроить их вывод; он не должен называться напрямую
report_success ()
Сообщите, что данный пример выполнен успешно. Этот метод предоставляется для того, чтобы подклассы DocTestRunner могли настраивать свой вывод; он не должен называться напрямую.
report_failure ()
Сообщите, что данный пример не удался. Этот метод позволяет подклассамDocTestRunnerнастроить их вывод; он не должен называться напрямую.
report_unexpected_exception ()
Сообщите, что в данном примере возникла непредвиденная исключительная ситуация. Этот метод предоставляется для того, чтобы подклассы DocTestRunner могли настраивать свой вывод; он не должен называться напрямую.
запустить (тест)
Запустите примеры в тесте (объект DocTest) и отобразите результаты с помощью функции записи out .
подвести итог ([подробный])
Распечатайте сводку всех тестовых случаев, которые были запущены этим DocTestRunner, и верните именованный кортеж TestResults (сбой, попытка). Необязательный многословный аргумент определяет, насколько подробным будет резюме. Если степень детализации не указана, используется степень детализации DocTestRunner.
OutputChecker Класс
Этот класс используется для проверки того, соответствует ли фактический вывод из примера doctest ожидаемому.
В этом классе определены следующие методы:
check_output ()
Возвращение Trueесли фактический результат из примера ( got ) совпадает с ожидаемым результатом ( хочу ). Эти строки всегда считаются совпадающими, если они идентичны; но в зависимости от того, какие флажки опций использует средство выполнения тестов, также возможно несколько типов неточного соответствия. See section Флаги опций и директивы для получения дополнительной информации о флагах опций.
output_difference ()
Вернуть строку, описывающую различия между ожидаемым выводом для данного примера ( пример ) и фактическим выводом ( полученным ).
Интеграция DocTest с Unittest
Модуль doctest предоставляет две функции, которые можно использовать для создания наборов модульных тестов из модулей и текстовых файлов, содержащих 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 () или run () модуля unittest.
Ниже приведены две основные функции для создания unittest.TestSuite экземпляры из текстовых файлов и модулей с тестами -
doctest.DocFileSuite ()
Он используется для преобразования тестов doctest из одного или нескольких текстовых файлов в unittest.TestSuite. Возвращенный unittest.TestSuite должен запускаться платформой unittest и запускать интерактивные примеры в каждом файле. Если какой-либо из примеров в файле терпит неудачу, то синтезированный модульный тест терпит неудачу, иfailureException возникает исключение, показывающее имя файла, содержащего тест, и (иногда приблизительный) номер строки.
doctest.DocTestSuite ()
Он используется для преобразования тестов doctest для модуля в unittest.TestSuite.
Возвращенный unittest.TestSuite должен запускаться платформой unittest и запускать каждый тест в модуле. Если какой-либо из тестов не прошел, то синтезированный модульный тест не прошел, иfailureException возникает исключение, показывающее имя файла, содержащего тест, и (иногда приблизительный) номер строки
Под обложками 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.