doctest - doctest

редактировать

doctest - это модуль, включенный в t Стандартная библиотека языка программирования Python, которая позволяет легко создавать тесты на основе вывода из стандартной оболочки интерпретатора Python, вырезать и вставлять в строки документации.

Содержание

  • 1 Особенности реализации
  • 2 Грамотное программирование и тесты документации
  • 3 Документирование библиотек на примере
  • 4 Примеры
    • 4.1 Пример 1: Доктест, встроенный в строку документации функции
    • 4.2 Пример 2: тесты документов, встроенные в файл README.txt
    • 4.3 Пример 3: unique_words.py
  • 5 Генераторы Doctest и документации
  • 6 Реализация на других языках программирования
  • 7 Ссылки

Особенности реализации

Doctest новаторски использует следующий Python возможности:

  • docstrings
  • Интерактивная оболочка Python (как командная строка, так и включенное простаивающее приложение)
  • Самоанализ Python

При использовании оболочки Python выполняется основное приглашение:>>>новыми командами. Вторичная подсказка:... используется при продолжении выполнения команд в нескольких строках; и результат выполнения команды ожидается в следующих строках. Пустая строка или другая строка, начинающаяся с основного приглашения, рассматривается как конец вывода команды.

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

Действие по умолчанию при запуске doctests - не показывать вывод, когда тесты проходят. Это может быть изменено с помощью опций программы запуска тестов. Кроме того, doctest интегрирован с модулем модульного тестирования Python, что позволяет запускать doctest как стандартные тестовые наборы unittest. Средство выполнения тестовых сценариев Unittest предоставляет больше возможностей при запуске тестов, таких как создание отчетов о тестовой статистике, например о пройденных и неудачных тестах.

Грамотное программирование и тесты

Хотя doctest не позволяет встраивать программу Python в повествовательный текст, он позволяет встраивать проверяемые примеры в строки документации, где строки документации могут содержать другой текст.. Строки документов, в свою очередь, можно извлекать из файлов программы для создания документации в других форматах, таких как HTML или PDF. Можно создать программный файл, содержащий документацию, тесты, а также код и тесты, легко проверяемые по коду. Это позволяет коду, тестам и документации развиваться вместе.

Документирование библиотек на примере

Доктесты хорошо подходят для ознакомления с библиотекой, демонстрируя, как используется API.

На основе вывода интерактивного интерпретатора Python текст может быть смешан с тестами, которые проверяют библиотеку, показывая ожидаемые результаты.

Примеры

Первый пример показывает, как повествовательный текст можно перемежать с тестируемыми примерами в строке документации. Во втором примере показаны другие функции doctest вместе с их пояснениями. Пример 3 настроен на запуск всех тестов в файле при запуске файла, но при импорте в виде модуля тесты не запускаются.

Пример 1: тест, встроенный в строку документации функции

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]

Пример 2: тесты, встроенные в файл README.txt

================== ==== Демонстрационные тесты документации ====================== Это всего лишь пример того, как выглядит текст README, который можно использовать с doctest.DocFileSuite () из модуля Python doctest. Обычно файл README объясняет API модуля, например:>>>a = 1>>>b = 2>>>a + b 3 Обратите внимание, что мы только что продемонстрировали, как складывать два числа в Python, и как будет выглядеть результат. Специальная опция позволяет вам быть нечетким в ваших примерах:>>>o = object ()>>>o # doctest: + ELLIPSIS Исключения также можно тестировать очень хорошо:>>>x Traceback (последний вызов last):... NameError: имя 'x' не определено

Пример 3: unique_words.py

В этом примере также имитируется ввод в функцию из файла с помощью модуля 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.

Ссылки

Последняя правка сделана 2021-05-17 10:44:06
Содержание доступно по лицензии CC BY-SA 3.0 (если не указано иное).
Обратная связь: support@alphapedia.ru