doctest - это модуль, включенный в t Стандартная библиотека языка программирования Python, которая позволяет легко создавать тесты на основе вывода из стандартной оболочки интерпретатора Python, вырезать и вставлять в строки документации.
Doctest новаторски использует следующий Python возможности:
При использовании оболочки Python выполняется основное приглашение:>>>новыми командами. Вторичная подсказка:... используется при продолжении выполнения команд в нескольких строках; и результат выполнения команды ожидается в следующих строках. Пустая строка или другая строка, начинающаяся с основного приглашения, рассматривается как конец вывода команды.
Модуль doctest ищет такие последовательности подсказок в строке документации, повторно выполняет извлеченную команду и сравнивает вывод с выводом команды, приведенной в примере проверки строк документации.
Действие по умолчанию при запуске doctests - не показывать вывод, когда тесты проходят. Это может быть изменено с помощью опций программы запуска тестов. Кроме того, doctest интегрирован с модулем модульного тестирования Python, что позволяет запускать doctest как стандартные тестовые наборы unittest. Средство выполнения тестовых сценариев Unittest предоставляет больше возможностей при запуске тестов, таких как создание отчетов о тестовой статистике, например о пройденных и неудачных тестах.
Хотя doctest не позволяет встраивать программу Python в повествовательный текст, он позволяет встраивать проверяемые примеры в строки документации, где строки документации могут содержать другой текст.. Строки документов, в свою очередь, можно извлекать из файлов программы для создания документации в других форматах, таких как HTML или PDF. Можно создать программный файл, содержащий документацию, тесты, а также код и тесты, легко проверяемые по коду. Это позволяет коду, тестам и документации развиваться вместе.
Доктесты хорошо подходят для ознакомления с библиотекой, демонстрируя, как используется API.
На основе вывода интерактивного интерпретатора Python текст может быть смешан с тестами, которые проверяют библиотеку, показывая ожидаемые результаты.
Первый пример показывает, как повествовательный текст можно перемежать с тестируемыми примерами в строке документации. Во втором примере показаны другие функции doctest вместе с их пояснениями. Пример 3 настроен на запуск всех тестов в файле при запуске файла, но при импорте в виде модуля тесты не запускаются.
def list_to_0_index (lst): "" "Решение проблемы, приведенное в: https://rgrig.blogspot.com/2005/ 11 / writing-readable-code.html 'Учитывая список lst, скажем, для каждого элемента индекс 0, где он появляется впервые. Итак, список x = [0, 1, 4, 2, 4, 1, 0, 2] преобразуется в y = [0, 1, 2, 3, 2, 1, 0, 3]. Обратите внимание, что для всех i мы имеем x [y [i]] = x [i]. Используйте любое программирование язык и любое представление данных, которое вы хотите ».>>>x = [0, 1, 4, 2, 4, 1, 0, 2]>>>list_to_0_index (x) [0, 1, 2, 3, 2, 1, 0, 3]>>>" "" return [lst.index (i) for i in lst]
================== ==== Демонстрационные тесты документации ====================== Это всего лишь пример того, как выглядит текст README, который можно использовать с doctest.DocFileSuite () из модуля Python doctest. Обычно файл README объясняет API модуля, например:>>>a = 1>>>b = 2>>>a + b 3 Обратите внимание, что мы только что продемонстрировали, как складывать два числа в Python, и как будет выглядеть результат. Специальная опция позволяет вам быть нечетким в ваших примерах:>>>o = object ()>>>o # doctest: + ELLIPSIS
В этом примере также имитируется ввод в функцию из файла с помощью модуля Python StringIO
def unique_words (page): '' 'Вернуть набор уникальных слов в списке строк текста. Пример:>>>from StringIO import StringIO>>>fileText = "" "кот сел на циновку... циновка была на коте... одна рыба две рыбы красная рыба... синяя рыба... это у рыбы желтая машина... У этой рыбы желтая звездочка "" ">>>file = StringIO (fileText)>>>page = file.readlines ()>>>words = unique_words (page)>>>print sorted (список (слова)) [«Это», «а», «синий», «машина», «кошка», «рыба», «имеет», «мат», «он», «ондур», «один», «красный», «сидел», «звезда», «тот», «два», «было», «желтый»]>>>'' 'возвращаемый набор (слово за строкой на странице за словом в строке.split ()) def _test (): import doctest doctest.testmod () if __name__ == "__main__": _test ()
Оба формата EpyText для Epydoc и формат reStructuredText Docutils поддерживают разметку разделов документации в строках документации.
В C ++ наиболее близкой возможной реализацией концепции является инфраструктура doctest - тесты могут быть написаны непосредственно в производственном коде с минимальными накладными расходами и возможностью их удаления из двоичного файла.
Библиотека ExUnit.DocTest Elixir реализует функциональность, аналогичную Doctest.
Реализация Doctest для Haskell.
Написание тестов документации на Элм.
Написание тестов документации на Rust.