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

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

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

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

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

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

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

• 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]

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

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

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 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 не задан;
• чтобы DocTestFinder не извлекал 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 — имя, идентифицирующее эту строку; оно используется только в сообщениях об ошибках.

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