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

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

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

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

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

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

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

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

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

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

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

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

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

Подробности:

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

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

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

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

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

• Начальный столбец не имеет значения:

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

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

Каков контекст выполнения?

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

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

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

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

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

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

Этот doctest проходит, если возникает исключение ValueError с указанным сообщением list.remove(x): x not in list.

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

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

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

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

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

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

Рекомендуется опускать стек вызовов, если только он не добавляет примеру существенной справочной ценности. Поэтому последний пример, вероятно, лучше записать так:

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

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

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

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

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

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

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

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

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

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

>>> 1000**0.1  # risky
1.9952623149688797
>>> round(1000**0.1, 9) # safer
1.995262315
>>> print(f'{1000**0.1:.4f}') # much safer
1.9953

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

>>> 3./4  # utterly safe
0.75

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

Объекты DocTest

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

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

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

examples

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

globs

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

name

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

filename

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

lineno

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

docstring

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

Объекты Example

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

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

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

source

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

want

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

exc_msg

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

lineno

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

indent

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

options

Словарь, сопоставляющий флаги параметров значениям True или False. Он используется для переопределения параметров по умолчанию для этого примера. Флаги параметров, отсутствующие в этом словаре, сохраняют значения по умолчанию (заданные атрибутом DocTestRunner 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 задаёт имя, идентифицирующее эту строку; оно используется только в сообщениях об ошибках.

Объекты TestResults

class doctest.TestResults(failed, attempted)

failed

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

attempted

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

skipped

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

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

Объекты DocTestRunner

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

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

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

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

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

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

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

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

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

report_start(out, test, example)

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

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

report_success(out, test, example, got)

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

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

report_failure(out, test, example, got)

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

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

report_unexpected_exception(out, test, example, exc_info)

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

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

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

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

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

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

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

summarize(verbose=None)

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

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

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

tries

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

failures

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

skips

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

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

Объекты OutputChecker

class doctest.OutputChecker

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

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

check_output(want, got, optionflags)

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

output_difference(example, got, optionflags)

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