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

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

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

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

<name of M>.__test__.K

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

Как распознаются примеры Docstring?¶

В большинстве случаев копирование и вставка интерактивной консольной сессии работает хорошо, но 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-колоночные упоры табуляции. Табуляции в выводе, генерируемом тестируемым кодом, не изменяются. Поскольку все символы табуляции в выводе примера расширяются, это означает, что если вывод кода включает символы табуляции, тест может пройти только в том случае, если действует опция NORMALIZE_WHITESPACE или directive. В качестве альтернативы, тест можно переписать так, чтобы перехватить вывод и сравнить его с ожидаемым значением как часть теста. Такой способ работы с табуляциями в исходном тексте был найден методом проб и ошибок и оказался наименее подверженным ошибкам. Можно использовать другой алгоритм обработки табуляции, написав собственный класс DocTestParser.

• Перехватывается вывод на stdout, но не вывод на stderr (трассировка исключений перехватывается другим способом).

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

  >>> 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, и имена, определенные ранее в выполняемой doc-строке. Примеры не могут видеть имена, определенные в других документах.

Вы можете принудительно использовать свой собственный dict в качестве контекста выполнения, передавая 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

Этот тест проходит успешно, если поднимается ValueError, с деталью list.remove(x): x not in list, как показано на рисунке.

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

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

За заголовком traceback следует необязательный стек traceback, содержимое которого игнорируется 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 или просто выведен текст трассировки. На практике обычный вывод редко начинается со строки заголовка traceback, поэтому это не создает реальных проблем.

• Каждая строка стека обратного следа (если она присутствует) должна быть отступлена дальше, чем первая строка примера, или начинаться с неалфавитно-цифрового символа. Первая строка, следующая за заголовком трассировки с таким же отступом и начинающаяся с буквенно-цифрового символа, принимается за начало детализации исключения. Конечно, это правильно для настоящих возвратов.

• Когда указана опция IGNORE_EXCEPTION_DETAIL doctest, все, что следует за крайним левым двоеточием, и любая информация о модуле в имени исключения игнорируется.

• Интерактивная оболочка опускает строку заголовка traceback для некоторых SyntaxErrors. Но doctest использует строку заголовка traceback, чтобы отличить исключения от неисключений. Поэтому в редких случаях, когда вам нужно протестировать SyntaxError, в котором опущен заголовок traceback, вам придется вручную добавить строку заголовка traceback в ваш тестовый пример.

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

  >>> 1 1
    File "<stdin>", line 1
      1 1
        ^
  SyntaxError: invalid syntax
  

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

  >>> 1 1
    File "<stdin>", line 1
      1 1
      ^
  SyntaxError: invalid syntax
  

Флаги опций¶

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

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

doctest.DONT_ACCEPT_TRUE_FOR_1¶

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

doctest.DONT_ACCEPT_BLANKLINE¶

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

doctest.NORMALIZE_WHITESPACE¶

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

doctest.ELLIPSIS¶

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

doctest.IGNORE_EXCEPTION_DETAIL¶

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

Например, пример, ожидающий 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¶

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

doctest.REPORT_CDIFF¶

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

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 могут быть использованы для изменения option flags для отдельного примера. Директивы 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]

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

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

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

>>> foo()
{"Hermione", "Harry"}

уязвима! Одно из обходных решений - сделать

>>> foo() == {"Hermione", "Harry"}
True

вместо. Другой вариант - сделать

>>> d = sorted(foo())
>>> d
['Harry', 'Hermione']

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

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

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

>>> 3./4  # utterly safe
0.75

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

Объекты DocTest¶

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

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

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

examples¶

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

globs¶

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

name¶

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

filename¶

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

lineno¶

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

docstring¶

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

Примеры объектов¶

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“optionflags). По умолчанию никакие опции не установлены.

Объекты DocTestFinder¶

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

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

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

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

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

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

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

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

Возвращает список DocTests, которые определены docstring’ом obj или docstring’ами любого из содержащихся в нем объектов.

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

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

• В качестве пространства имен по умолчанию, если не указано globs.

• Чтобы предотвратить извлечение DocTestFinder’ом DocTests из объектов, импортированных из других модулей. (Содержащиеся объекты с модулями, отличными от module, игнорируются).

• Чтобы найти имя файла, содержащего объект.

• Помогает найти номер строки объекта в его файле.

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

Словарь globals для каждого DocTest формируется путем объединения globs и extraglobs (привязки в extraglobs переопределяют привязки в globs). Для каждого DocTest создается новая неглубокая копия словаря globals. Если 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. Номера строк основаны на 0. Необязательный аргумент name является именем, идентифицирующим данную строку, и используется только для сообщений об ошибках.

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

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

Объекты DocTestRunner¶

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

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

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

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

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

report_start(out, test, example)¶

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

example - это пример, который будет обработан. test - это тест, содержащий пример. 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) и выведите результаты с помощью функции writer out.

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

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

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

summarize(verbose=None)¶

Выводит сводку всех тестовых случаев, которые были запущены этим DocTestRunner, и возвращает named tuple 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.