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

Какие строковые документы анализируются?

Проверяются строковые документы модуля и всех функций, классов и методов. Объекты, импортированные в модуль, не проверяются.

Кроме того, есть случаи, когда вы хотите, чтобы тесты были частью модуля, но не частью справочной информации, что требует, чтобы тесты не включались в строковый документ. Doctest ищет переменную уровня модуля, называемую __test__, и использует ее для поиска других тестов. Если M.__test__ существует, она должна быть словарем, и каждое значение сопоставляет (строку) имя с объектом функции, объектом класса или строкой. Строковые документы функций и объектов классов, найденные из M.__test__, проверяются, а строки обрабатываются так, как если бы они были строковыми документами. В выводе ключ K в M.__test__ появляется с именем M.__test__.K.

Например, поместите этот блок кода в начало example.py:

__test__ = {
    'numbers': """
>>> factorial(6)
720

>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
"""
}

Значение example.__test__["numbers"] будет обрабатываться как строковый документ, и все тесты внутри него будут выполняться. Важно отметить, что значение может быть сопоставлено с функцией, объектом класса или модулем; если это так, doctest рекурсивно ищет их для строковых документов, которые затем сканируются на наличие тестов.

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

Как распознаются примеры в строковых документах?

В большинстве случаев копирование и вставка сеанса интерактивной консоли работают нормально, но doctest не пытается точно эмулировать какую-либо конкретную оболочку Python.

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print("yes")
... else:
...     print("no")
...     print("NO")
...     print("NO!!!")
...
no
NO
NO!!!
>>>

Любой ожидаемый вывод должен немедленно следовать за последней строкой кода '>>> ' или '... ', а ожидаемый вывод (если есть) простирается до следующей строки '>>> ' или строки, состоящей только из пробелов.

Мелкие детали:

• Ожидаемый вывод не может содержать строку, состоящую только из пробелов, так как такая строка считается сигналом окончания ожидаемого вывода. Если ожидаемый вывод содержит пустую строку, поместите <BLANKLINE> в свой пример doctest каждый раз, когда ожидается пустая строка.
• Все символы табуляции расширяются до пробелов, используя 8-колонные позиции табуляции. Табуляции в выводе, сгенерированном тестируемым кодом, не изменяются. Поскольку любые жесткие табуляции в образце вывода расширяются, это означает, что если вывод кода содержит жесткие табуляции, единственный способ, которым doctest может пройти, это если опция NORMALIZE_WHITESPACE или директива активна. В качестве альтернативы тест можно переписать, чтобы захватить вывод и сравнить его с ожидаемым значением в рамках теста. Такое обработка табуляции в исходном коде была получена методом проб и ошибок и оказалась наименее подверженной ошибкам. Можно использовать другой алгоритм обработки табуляции, написав пользовательский класс DocTestParser.
• Вывод в стандартный вывод (stdout) захватывается, но не вывод в стандартный поток ошибок (stderr) (обработка исключений захватывается с помощью другого метода).

• Если вы продолжаете строку с помощью обратного слэша в интерактивной сессии или по любой другой причине используете обратный слэш, вам следует использовать сырую строку, которая сохранит ваши обратные слэши точно так, как вы их ввели:

  >>> def f(x):
  ...     r'''Backslashes in a raw docstring: m\n'''
  ...
  >>> print(f.__doc__)
  Backslashes in a raw docstring: m\n
  

  В противном случае обратный слэш будет интерпретироваться как часть строки. Например, \n выше будет интерпретироваться как символ новой строки. В качестве альтернативы можно удвоить каждый обратный слэш в версии doctest (и не использовать сырую строку):

  >>> def f(x):
  ...     '''Backslashes in a raw docstring: m\\n'''
  ...
  >>> print(f.__doc__)
  Backslashes in a raw docstring: m\n
  

• Начальная колонка не имеет значения:

  >>> assert "Easy!"
        >>> import math
            >>> math.floor(1.9)
            1
  

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

Какой контекст выполнения используется?

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

Вы можете принудительно использовать свой собственный словарь в качестве контекста выполнения, передав globs=your_dict в testmod() или testfile().

Что насчет исключений?

Без проблем, при условии, что трассировка стека — единственный вывод, создаваемый примером: просто вставьте трассировку стека. [1] Поскольку трассировки стека содержат детали, которые, вероятно, быстро изменятся (например, точные пути к файлам и номера строк), это один из случаев, когда doctest прилагает усилия, чтобы быть гибким в том, что он принимает.

Простой пример:

>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list

Этот doctest выполняется успешно, если возбуждено ValueError с деталью list.remove(x): x not in list в виде показанной.

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

Traceback (most recent call last):
Traceback (innermost last):

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

Стек трассировки следует за самой интересной частью: строкой(ами), содержащей тип исключения и детали. Обычно это последняя строка трассировки, но может простираться на несколько строк, если исключение имеет многострочный элемент:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: multi
    line
detail

Последние три строки (начиная с ValueError) сравниваются с типом и деталями исключения, а остальные игнорируются.

Лучшей практикой является опускание стека трассировки, если он не добавляет значительной документационной ценности к примеру. Так что последний пример, вероятно, лучше в виде:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
    ...
ValueError: multi
    line
detail

Обратите внимание, что трассировки стеков обрабатываются очень специально. В частности, в переписанном примере использование ... независимо от опции doctest ELLIPSIS. Многоточие в этом примере можно опустить, или же можно использовать три (или триста) запятых или цифр, или отформатированный текст из сцены комедийного шоу «Монти Пайтон».

Некоторые детали, которые вы должны прочитать один раз, но не нужно запоминать:

• Doctest не может угадать, был ли ожидаемый вывод из трассировки стека исключения или из обычного вывода. Таким образом, например, пример, который ожидает ValueError: 42 is prime, пройдет, будет ли возбуждено ValueError или если пример просто выводит этот текст трассировки стека. На практике обычный вывод редко начинается с строки заголовка трассировки стека, поэтому это не создает реальных проблем.
• Каждая строка стека трассировки (если присутствует) должна быть отступлена дальше, чем первая строка примера, или начинаться с неалфавитно-цифрового символа. Первая строка, следующая за заголовком трассировки стека, отступы которой совпадают и которая начинается с алфавитно-цифрового символа, считается началом деталей исключения. Конечно, это делает правильную работу для реальных трассировок стека.
• Когда указана опция doctest IGNORE_EXCEPTION_DETAIL, всё после левой точки с запятой и любой информации о модуле в имени исключения игнорируется.
• Интерактивная оболочка опускает строку заголовка трассировки стека для некоторых SyntaxErrorов. Но doctest использует строку заголовка трассировки стека для различения исключений от неисключений. Поэтому в редких случаях, когда вам нужно протестировать SyntaxError, который опускает строку заголовка трассировки стека, вам необходимо вручную добавить строку заголовка трассировки стека в ваш пример теста.

• Для некоторых исключений Python отображает положение ошибки с помощью маркеров ^ и тильдов:

  >>> 1 + None
    File "<stdin>", line 1
      1 + None
      ~~^~~~~~
  TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
  

  Поскольку строки, показывающие положение ошибки, появляются до типа и деталей исключения, они не проверяются doctest. Например, следующий тест пройдет, даже если он поместит маркер ^ в неправильное место:

  >>> 1 + None
    File "<stdin>", line 1
      1 + None
      ^~~~~~~~
  TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
  

Флаги параметров

Ряд флагов параметров управляют различными аспектами поведения doctest. Символьные имена флагов предоставляются в виде констант модуля, которые могут быть побитово объединены OR и переданы различным функциям. Эти имена также могут использоваться в директивах doctest и могут быть переданы в командную строку doctest через параметр -o.

Первая группа параметров определяет семантику теста, контролируя аспекты того, как doctest определяет, соответствует ли фактический вывод ожидаемому выводу примера:

doctest.DONT_ACCEPT_TRUE_FOR_1

По умолчанию, если блок ожидаемого вывода содержит только 1, блок фактического вывода, содержащий только 1 или только True, считается совпадающим, и аналогично для 0 и False. При указании DONT_ACCEPT_TRUE_FOR_1 ни одна из подстановок не допускается. По умолчанию поведение учитывает, что Python изменил тип возвращаемого значения многих функций с целого на булево; doctest, ожидающие «целочисленного» вывода, по-прежнему работают в этих случаях. Этот параметр, вероятно, будет удален, но не в ближайшие несколько лет.

doctest.DONT_ACCEPT_BLANKLINE

По умолчанию, если блок ожидаемого вывода содержит строку, содержащую только строку <BLANKLINE>, то эта строка будет соответствовать пустой строке в фактическом выводе. Поскольку действительно пустая строка ограничивает ожидаемый вывод, это единственный способ указать, что ожидается пустая строка. При указании DONT_ACCEPT_BLANKLINE эта подстановка не допускается.

doctest.NORMALIZE_WHITESPACE

При указании все последовательности пробелов (пробелов и символов новой строки) обрабатываются как равные. Любая последовательность пробелов в ожидаемом выводе будет соответствовать любой последовательности пробелов в фактическом выводе. По умолчанию пробелы должны точно совпадать. NORMALIZE_WHITESPACE особенно полезно, когда строка ожидаемого вывода очень длинная, и вы хотите её переносить на несколько строк в вашем исходном коде.

doctest.ELLIPSIS

При указании маркер многоточия (...) в ожидаемом выводе может соответствовать любому подстроке в фактическом выводе. Это включает подстроки, которые охватывают границы строк, и пустые подстроки, поэтому лучше всего сохранять простоту использования. Сложные применения могут привести к тем же неожиданностям «опс, он совпал слишком много!», что и .* в регулярных выражениях.

doctest.IGNORE_EXCEPTION_DETAIL

При указании doctest, ожидающие исключения, проходят, если возникает исключение нужного типа, даже если детали (сообщение и полное имя исключения) не совпадают.

Например, пример, ожидающий ValueError: 42, пройдет, если фактически возникло исключение ValueError: 3*14, но потерпит неудачу, если вместо этого возникнет, например, TypeError. Он также проигнорирует любое полное квалифицированное имя, включенное перед классом исключения, которое может отличаться в разных реализациях и версиях Python и используемого кода/библиотек. Таким образом, все три этих варианта будут работать с указанным флагом:

>>> raise Exception('message')
Traceback (most recent call last):
Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
builtins.Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
__main__.Exception: message

Обратите внимание, что ELLIPSIS также можно использовать для игнорирования деталей сообщения об исключении, но такой тест все равно может потерпеть неудачу в зависимости от того, присутствует ли имя модуля или точно совпадает.

Изменено в версии 3.2:IGNORE_EXCEPTION_DETAIL теперь также игнорирует любую информацию, относящуюся к модулю, содержащему исключение, которое тестируется.

doctest.SKIP

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

Флаг SKIP также можно использовать для временного «комментирования» примеров.

doctest.COMPARISON_FLAGS

Побитовая маска, объединяющая все флаги сравнения выше.

Вторая группа параметров управляет тем, как сообщаются о неудачах теста:

doctest.REPORT_UDIFF

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

doctest.REPORT_CDIFF

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

doctest.REPORT_NDIFF

При указании различия вычисляются с помощью difflib.Differ, используя тот же алгоритм, что и популярная утилита ndiff.py. Это единственный метод, который отмечает различия как внутри строк, так и между ними. Например, если строка ожидаемого вывода содержит цифру 1, а строка фактического вывода содержит букву l, вставляется строка с символом «^», отмечающая позиции несовпадающих столбцов.

doctest.REPORT_ONLY_FIRST_FAILURE

При указании отображается первый не пройденный пример в каждом doctest, но вывод всех остальных примеров подавляется. Это предотвратит doctest от отображения корректных примеров, которые сломались из-за предыдущих неудач; но также может скрыть неправильные примеры, которые терпят неудачу независимо от первой неудачи. При указании REPORT_ONLY_FIRST_FAILURE, оставшиеся примеры всё равно выполняются и всё ещё учитываются в общем количестве сообщенных неудач; только вывод подавляется.

doctest.FAIL_FAST

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

Командная строка doctest принимает опцию -f в качестве сокращения для -o FAIL_FAST.

Добавлен в версии 3.4.

doctest.REPORTING_FLAGS

Побитовая маска, объединяющая все флаги отчетов выше.

Также есть способ регистрации новых имён флагов параметров, хотя это не пригодится, если вы не намерены расширять doctest внутренности с помощью наследования:

doctest.register_optionflag(name)

Создаёт новый флаг параметра с заданным именем и возвращает целое значение нового флага. register_optionflag() может использоваться при наследовании от OutputChecker или DocTestRunner для создания новых параметров, которые поддерживаются вашими подклассами. register_optionflag() всегда следует вызывать с помощью следующего выражения:

MY_FLAG = register_optionflag('MY_FLAG')

Директивы

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

directive             ::=  "#" "doctest:" directive_options
directive_options     ::=  directive_option ("," directive_option)*
directive_option      ::=  on_or_off directive_option_name
on_or_off             ::=  "+" | "-"
directive_option_name ::=  "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...

Пробелы не допускаются между + или - и именем параметра директивы. Имя параметра директивы может быть любым из имен флагов параметров, описанных выше.

Директивы doctest примера изменяют поведение doctest для этого единственного примера. Используйте + для включения указанного поведения или - для его отключения.

Например, этот тест проходит:

>>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

Без директивы он потерпит неудачу, как из-за того, что фактический вывод не имеет двух пробелов перед элементами списка с однозначными числами, так и потому, что фактический вывод находится на одной строке. Этот тест также проходит и также требует директивы для этого:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]

Несколько директив могут использоваться в одной физической строке, разделённые запятыми:

>>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

Если для одного примера используются несколько комментариев директивы, то они объединяются:

>>> print(list(range(20)))  # doctest: +ELLIPSIS
...                         # doctest: +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]

Как показывает предыдущий пример, можно добавить ... строки в ваш пример, содержащие только директивы. Это может быть полезно, когда пример слишком длинный, чтобы директива поместилась на той же строке:

>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
[0, ..., 4, 10, ..., 19, 30, ..., 39]

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

Предупреждения

doctest серьёзно относится к требованию точного соответствия в ожидаемом выводе. Если даже один символ не совпадает, тест завершается неудачей. Это, вероятно, несколько вас удивит, когда вы узнаете точно, что Python гарантирует, а что нет, относительно вывода. Например, при печати набора Python не гарантирует, что элементы будут напечатаны в каком-либо определённом порядке, поэтому тест, подобный

>>> foo()
{"spam", "eggs"}

уязвим! Одно решение — сделать

>>> foo() == {"spam", "eggs"}
True

Другое — сделать

>>> d = sorted(foo())
>>> d
['eggs', 'spam']

Существуют и другие, но вы поняли суть.

Ещё одна плохая идея — печатать вещи, которые включают адрес объекта, например

>>> id(1.0)  # certain to fail some of the time  
7948648
>>> class C: pass
>>> C()  # the default repr() for instances embeds an address   
<C object at 0x00AC18F0>

Директива ELLIPSIS предлагает хороший подход для последнего примера:

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

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

>>> 1./7  # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857

Числа вида I/2.**J безопасны на всех платформах, и я часто составляю примеры doctest для получения чисел такого вида:

>>> 3./4  # utterly safe
0.75

Простые дроби также легче понять людям, и это делает документацию лучше.

Объекты DocTest

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)

Коллекция примеров doctest, которые должны выполняться в одном пространстве имён. Аргументы конструктора используются для инициализации атрибутов с теми же именами.

DocTest определяет следующие атрибуты. Они инициализируются конструктором и не должны изменяться напрямую.

examples

Список объектов Example, кодирующих отдельные интерактивные Python-примеры, которые должны быть выполнены этим тестом.

globs

Пространство имён (также известное как глобальные переменные), в котором должны выполняться примеры. Это словарь, сопоставляющий имена со значениями. Любые изменения в пространстве имён, внесённые примерами (например, привязка новых переменных), будут отражены в globs после выполнения теста.

name

Строковое имя, идентифицирующее DocTest. Обычно это имя объекта или файла, из которого был извлечён тест.

filename

Имя файла, из которого был извлечён этот DocTest; или None если имя файла неизвестно или DocTest не был извлечён из файла.

lineno

Номер строки в filename, где начинается этот DocTest, или None если номер строки недоступен. Номер строки нулевой относительно начала файла.

docstring

Строка, из которой был извлечён тест, или None если строка недоступна или тест не был извлечён из строки.

Объекты Example

class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)

Один интерактивный пример, состоящий из Python-выражения и его ожидаемого вывода. Аргументы конструктора используются для инициализации атрибутов с теми же именами.

Example определяет следующие атрибуты. Они инициализируются конструктором и не должны изменяться напрямую.

source

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

want

Ожидаемый вывод от выполнения исходного кода примера (либо из стандартного потока вывода, либо отслеживания исключения в случае исключения). want заканчивается новой строкой, если ожидаемый вывод не пустой, в противном случае это пустая строка. Конструктор добавляет новую строку при необходимости.

exc_msg

Сообщение об исключении, сгенерированное примером, если ожидается, что пример сгенерирует исключение; или None если не ожидается генерация исключения. Это сообщение об исключении сравнивается со значением возврата traceback.format_exception_only(). exc_msg заканчивается новой строкой, если это не None. Конструктор добавляет новую строку, если нужно.

lineno

Номер строки в строке, содержащей этот пример, где начинается пример. Номер строки нулевой относительно начала содержащей строки.

indent

Отступ примера в содержащей строке, т. е. количество пробелов, предшествующих первой подсказке примера.

options

Словарь, сопоставляющий флаги опций с True или False, используемый для переопределения значений параметров по умолчанию для этого примера. Любые флаги опций, не содержащиеся в этом словаре, остаются в своём значении по умолчанию (как указано в DocTestRunner’s optionflags). По умолчанию параметры не установлены.

Объекты DocTestFinder

class doctest.DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

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

Необязательный аргумент verbose может быть использован для отображения объектов, просматриваемых поисковиком. По умолчанию он равен False (нет вывода).

Необязательный аргумент parser задаёт объект DocTestParser (или его аналог), используемый для извлечения тестов doctest из строк документации.

Если необязательный аргумент recurse имеет значение false, тогда DocTestFinder.find() будет проверять только заданный объект, а не любые вложенные объекты.

Если необязательный аргумент exclude_empty имеет значение false, тогда DocTestFinder.find() будет включать тесты для объектов с пустыми строками документации.

DocTestFinder определяет следующий метод:

find(obj[, name][, module][, globs][, extraglobs])

Возвращает список DocTestов, которые определены строкой документации obj или любой из строк документации вложенных объектов.

Необязательный аргумент name задаёт имя объекта; это имя будет использовано для построения имён возвращаемых DocTestов. Если name не указан, то используется obj.__name__.

Необязательный параметр module — модуль, содержащий данный объект. Если модуль не указан или равен None, поиск модуля будет выполнен автоматически. Модуль объекта используется:

• В качестве пространства имён по умолчанию, если globs не указан.
• Для предотвращения извлечения DocTestов из объектов, импортированных из других модулей. (Вложенные объекты с модулями, отличными от module, игнорируются.)
• Для поиска имени файла, содержащего объект.
• Для поиска строки объекта в его файле.

Если module равно False, попытка найти модуль не будет предпринята. Это нечасто используется, в основном для тестирования самого doctest: если module равно False, или равно None, но не может быть найдено автоматически, то все объекты считаются принадлежащими несуществующему модулю, поэтому все вложенные объекты будут (рекурсивно) проверены на наличие тестов doctest.

Глобальные переменные для каждого DocTest формируются путём объединения globs и extraglobs (связанные в extraglobs переопределяют связи в globs). Для каждого DocTest создаётся новая поверхностная копия словаря глобальных переменных. Если globs не указан, по умолчанию используется __dict__ модуля, если задан, или {} в противном случае. Если extraglobs не указан, он по умолчанию равен {}.

Объекты DocTestParser

class doctest.DocTestParser

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

DocTestParser определяет следующие методы:

get_doctest(string, globs, name, filename, lineno)

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

globs, name, filename и lineno являются атрибутами нового объекта DocTest. Более подробная информация содержится в документации по DocTest.

get_examples(string, name='<string>')

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

parse(string, name='<string>')

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

Объекты TestResults

class doctest.TestResults(failed, attempted)

failed

Количество неудавшихся тестов.

attempted

Количество попытанных тестов.

skipped

Количество пропущенных тестов.

Добавлен в версии 3.13.

Объекты DocTestRunner

class doctest.DocTestRunner(checker=None, verbose=None, optionflags=0)

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

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

Вывод результатов работы тестового исполнителя можно контролировать двумя способами. Во-первых, можно передать функцию вывода в run(); эта функция будет вызываться со строками, которые необходимо отобразить. По умолчанию это sys.stdout.write. Если захват вывода недостаточен, то вывод можно также настроить, создав подкласс DocTestRunner и переопределив методы report_start(), report_success(), report_unexpected_exception() и report_failure().

Необязательный ключевой аргумент checker задаёт объект OutputChecker (или его замену), который используется для сравнения ожидаемого вывода с фактическим выводом примеров doctest.

Необязательный ключевой аргумент verbose контролирует подробность вывода DocTestRunner. Если verbose True, то выводится информация о каждом примере во время его выполнения. Если verbose False, то выводится только информация о неудачах. Если verbose не указан или None, то подробный вывод используется только в том случае, если используется командная строка -v.

Необязательный ключевой аргумент optionflags может использоваться для управления тем, как тестовый исполнитель сравнивает ожидаемый вывод с фактическим выводом и отображает ошибки. Для получения дополнительной информации см. раздел Флаги опций.

Тестовый исполнитель накапливает статистику. Общее количество попыток, неудач и пропущенных примеров также доступно через атрибуты tries, failures и skips. Методы run() и summarize() возвращают экземпляр TestResults.

DocTestRunner определяет следующие методы:

report_start(out, test, example)

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

example — пример, который собирается обработать. test — тест, содержащий example. out — функция вывода, переданная в DocTestRunner.run().

report_success(out, test, example, got)

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

example — пример, который собирается обработать. got — фактический вывод примера. test — тест, содержащий example. out — функция вывода, переданная в DocTestRunner.run().

report_failure(out, test, example, got)

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

example — пример, который собирается обработать. got — фактический вывод примера. test — тест, содержащий example. out — функция вывода, переданная в DocTestRunner.run().

report_unexpected_exception(out, test, example, exc_info)

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

example — пример, который собирается обработать. exc_info — кортеж, содержащий информацию об исключении (как возвращается sys.exc_info()). test — тест, содержащий example. out — функция вывода, переданная в DocTestRunner.run().

run(test, compileflags=None, out=None, clear_globs=True)

Выполнить примеры в test (объект DocTest) и отобразить результаты с помощью функции записи out. Вернуть экземпляр TestResults.

Примеры выполняются в пространстве имён test.globs. Если clear_globs истинно (по умолчанию), то это пространство имён будет очищено после выполнения теста, чтобы помочь с утилизацией памяти. Если вы хотите исследовать пространство имён после завершения теста, используйте clear_globs=False.

compileflags задаёт набор флагов, которые должны использоваться компилятором Python при выполнении примеров. Если не указано, то по умолчанию используется набор флагов future-import, которые применяются к globs.

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

summarize(verbose=None)

Вывести сводку всех протестированных случаев, обработанных этим DocTestRunner, и вернуть экземпляр TestResults.

Необязательный аргумент verbose управляет подробностью сводки. Если подробность не указана, то используется подробность DocTestRunner.

DocTestParser имеет следующие атрибуты:

tries

Количество попыток примеров.

failures

Количество неудачных примеров.

skips

Количество пропущенных примеров.

Добавлен в версии 3.13.

Объекты OutputChecker

class doctest.OutputChecker

Класс, используемый для проверки соответствия фактического вывода из примера doctest ожидаемому выводу. OutputChecker определяет два метода: check_output(), который сравнивает заданную пару выводов и возвращает True если они совпадают; и output_difference(), который возвращает строку, описывающую различия между двумя выводами.

OutputChecker определяет следующие методы:

check_output(want, got, optionflags)

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

output_difference(example, got, optionflags)

Возвращает строку, описывающую различия между ожидаемым выводом для данного примера (example) и фактическим выводом (got). optionflags — это набор флагов опций, используемых для сравнения want и got.