доктор

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

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

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

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

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

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

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

Грамотное программирование и документация

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

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

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

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

Примеры

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

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

def list_to_0_index(lst):
    """A solution to the problem given in:
    https://rgrig.blogspot.com/2005/11/writing-readable-code.html

    'Given a list, lst, say for each element the 0-index where it appears for
    the first time. So the list x = [0, 1, 4, 2, 4, 1, 0, 2] is
    transformed into y = [0, 1, 2, 3, 2, 1, 0, 3]. Notice that for all
    i we have x[y[i]] = x[i]. Use any programming language and any data
    representation you want.'

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

======================
Demonstration doctests
======================

This is just an example of what a README text looks like that can be used with
the doctest.DocFileSuite() function from Python's doctest module.

Normally, the README file would explain the API of the module, like this:

>>> a = 1
>>> b = 2
>>> a + b
3

Notice, that we just demonstrated how to add two numbers in Python, and 
what the result will look like.

A special option allows you to be somewhat fuzzy about your examples:

>>> o = object()
>>> o                 # doctest: +ELLIPSIS
<object object at 0x...>

Exceptions can be tested very nicely too:

>>> x
Traceback (most recent call last):
 ...
NameError: name 'x' is not defined

Пример 3: unique_words.py

В этом примере также моделируется ввод в функцию из файла с помощью модуля Python StringIO.

def unique_words(page):
    """Return set of the unique words in list of lines of text.

    Example:

    >>> from StringIO import StringIO
    >>> fileText = '''the cat sat on the mat
    ... the mat was ondur the cat
    ... one fish two fish red fish
    ... blue fish
    ... This fish has a yellow car
    ... This fish has a yellow star'''
    >>> file = StringIO(fileText)
    >>> page = file.readlines()
    >>> words = unique_words(page)
    >>> print sorted(list(words))
    ["This", "a", "blue", "car", "cat", "fish", "has", "mat",
     "on", "ondur", "one", "red", "sat", "star", "the", "two",
     "was", "yellow"]
    >>>
    """
    return set(word for line in page for word in line.split())

def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()

Генераторы документов и документации

И формат EpyText Epydoc Docutils , и формат reStructuredText поддерживают разметку разделов документации в строках документации.

Реализация на других языках программирования

В C++ фреймворк doctest является наиболее близкой реализацией этой концепции: тесты можно писать непосредственно в рабочем коде с минимальными накладными расходами и возможностью их удаления из двоичного файла.

Библиотека ExUnit.DocTest Elixir реализует функциональность, аналогичную Doctest.

Реализация Doctest для Haskell .

Написание тестов документации в Elm .

Написание тестов документации на Rust .

Написание тестов документации в Elixir .

byexample поддерживает написание документов для нескольких популярных языков программирования (например, Python, Ruby, Shell, JavaScript, C/C++, Java, Go, Rust) внутри Markdown , reStructuredText и других текстовых документов.

Внешние ссылки

• doctest — интерактивные примеры тестирования Python