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. Эллипсис в этом примере может быть опущен или может быть заменен на три (или три сотни) запятых, цифр или отступом сценария Monty Python.

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

• 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. Символьные имена флагов предоставляются в качестве констант модуля, которые могут быть побитово объединены и переданы в различные функции. Эти имена также могут использоваться в директивах 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

Ожидаемый вывод от выполнения исходного кода примера (либо из stdout, либо трассировка стека в случае исключения). 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 (или его замену), который используется для извлечения тестов из строк документации.

Если необязательный аргумент 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 формируются путём объединения 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 — имя, идентифицирующее эту строку, и используется только для сообщений об ошибках.

Объекты 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 может использоваться для управления тем, как тест сравнивает ожидаемый вывод с фактическим, а также как отображает ошибки. Дополнительная информация представлена в разделе Флаги параметров.

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.

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

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

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

summarize(verbose=None)

Вывести сводку всех тестов, выполненных этим DocTestRunner, и вернуть кортеж TestResults(failed, attempted).

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

Объекты 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.