doctest — 测试交互式 Python 示例¶
源代码： Lib/doctest.py
doctest 模块搜索看起来像交互式 Python 会话的文本片段，然后执行这些会话以验证它们是否按所示方式工作。有几种常见的方法可以使用 doctest：
通过验证所有交互式示例是否仍然像文档中描述的那样工作，来检查模块的文档字符串是否是最新的。
通过验证测试文件或测试对象中的交互式示例是否按预期工作来执行回归测试。
为软件包编写教程文档，其中大量使用输入输出示例进行说明。根据强调的是示例还是说明性文本，这具有“文学测试”或“可执行文档”的味道。
这是一个完整但小的示例模块
"""
This is the "example" module.
The example module supplies one function, factorial(). For example,
>>> factorial(5)
120
"""
def factorial(n):
"""Return the factorial of n, an exact integer >= 0.
>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> factorial(30)
265252859812191058636308480000000
>>> factorial(-1)
Traceback (most recent call last):
...
ValueError: n must be >= 0
Factorials of floats are OK, but the float must be an exact integer:
>>> factorial(30.1)
Traceback (most recent call last):
...
ValueError: n must be exact integer
>>> factorial(30.0)
265252859812191058636308480000000
It must also not be ridiculously large:
>>> factorial(1e100)
Traceback (most recent call last):
...
OverflowError: n too large
"""
import math
if not n >= 0:
raise ValueError("n must be >= 0")
if math.floor(n) != n:
raise ValueError("n must be exact integer")
if n+1 == n: # catch a value like 1e300
raise OverflowError("n too large")
result = 1
factor = 2
while factor <= n:
result *= factor
factor += 1
return result
if __name__ == "__main__":
import doctest
doctest.testmod()
如果您直接从命令行运行 example.py，doctest 会发挥其魔力：
$ python example.py
$
没有输出！这是正常的，这意味着所有示例都有效。将 -v 传递给脚本，doctest 会打印它正在尝试的详细日志，并在最后打印摘要：
$ python example.py -v
Trying:
factorial(5)
Expecting:
120
ok
Trying:
[factorial(n) for n in range(6)]
Expecting:
[1, 1, 2, 6, 24, 120]
ok
等等，最终以以下内容结束：
Trying:
factorial(1e100)
Expecting:
Traceback (most recent call last):
...
OverflowError: n too large
ok
2 items passed all tests:
1 test in __main__
6 tests in __main__.factorial
7 tests in 2 items.
7 passed.
Test passed.
$
这就是您开始有效使用 doctest 所需了解的全部内容！开始吧。以下部分提供完整详细信息。请注意，在标准 Python 测试套件和库中有很多 doctest 示例。特别有用的示例可以在标准测试文件 Lib/test/test_doctest/test_doctest.py 中找到。
简单用法：检查文档字符串中的示例¶
开始使用 doctest 的最简单方法（但不一定是你继续使用它的方式）是在每个模块 M 的末尾添加：
if __name__ == "__main__":
import doctest
doctest.testmod()
doctest 然后检查模块 M 中的文档字符串。
将模块作为脚本运行会导致文档字符串中的示例被执行和验证。
python M.py
除非示例失败，否则这不会显示任何内容，在这种情况下，失败的示例和失败的原因将打印到 stdout，并且输出的最后一行是 ***Test Failed*** N failures.，其中 *N* 是失败的示例数量。
改为使用 -v 开关运行它：
python M.py -v
所有尝试的示例的详细报告将打印到标准输出，以及最后各种摘要。
您可以通过将 verbose=True 传递给 testmod() 来强制使用详细模式，或通过传递 verbose=False 来禁止它。在任何一种情况下，testmod() 都不会检查 sys.argv（因此传递 -v 或不传递都没有效果）。
还有一个用于运行 testmod() 的命令行快捷方式。您可以指示 Python 解释器直接从标准库运行 doctest 模块，并在命令行中传递模块名称：
python -m doctest -v example.py
这将导入 example.py 作为独立模块，并在其上运行 testmod()。请注意，如果文件是包的一部分并从该包导入其他子模块，则此操作可能无法正常工作。
简单用法：检查文本文件中的示例¶
doctest 的另一个简单应用是测试文本文件中的交互式示例。这可以使用 testfile() 函数完成：
import doctest
doctest.testfile("example.txt")
该简短的脚本执行并验证文件 example.txt 中包含的任何交互式 Python 示例。文件内容被视为单个巨大的文档字符串；该文件不需要包含 Python 程序！例如，也许 example.txt 包含以下内容：
The ``example`` module
======================
Using ``factorial``
-------------------
This is an example text file in reStructuredText format. First import
``factorial`` from the ``example`` module:
>>> from example import factorial
Now use it:
>>> factorial(6)
120
然后运行 doctest.testfile("example.txt") 会在此文档中发现错误：
File "./example.txt", line 14, in example.txt
Failed example:
factorial(6)
Expected:
120
Got:
720
与 testmod() 一样，testfile() 除非示例失败，否则不会显示任何内容。如果示例确实失败，则失败的示例和失败的原因将使用与 testmod() 相同的格式打印到 stdout。
默认情况下，testfile() 在调用模块的目录中查找文件。有关可用于指示其在其他位置查找文件的可选参数的说明，请参阅 基本 API 部分。
与 testmod() 一样，可以使用 -v 命令行开关或可选的关键字参数 *verbose* 设置 testfile() 的详细程度。
还有一个用于运行 testfile() 的命令行快捷方式。您可以指示 Python 解释器直接从标准库运行 doctest 模块，并在命令行中传递文件名：
python -m doctest -v example.txt
由于文件名不是以 .py 结尾，doctest 会推断它必须使用 testfile() 运行，而不是 testmod()。
关于 testfile() 的更多信息，请参阅 基本 API 部分。
工作原理¶
本节详细探讨 doctest 的工作原理：它会查看哪些文档字符串，如何查找交互式示例，它使用什么执行上下文，如何处理异常，以及如何使用选项标志来控制其行为。这是您编写 doctest 示例需要了解的信息；有关在这些示例上实际运行 doctest 的信息，请参阅以下部分。
检查哪些文档字符串？¶
会搜索模块文档字符串以及所有函数、类和方法的文档字符串。不会搜索导入到模块中的对象。
此外，在某些情况下，您希望测试成为模块的一部分，但不是帮助文本的一部分，这要求测试不包含在文档字符串中。Doctest 会查找名为 __test__ 的模块级变量，并使用它来查找其他测试。如果 M.__test__ 存在，它必须是一个字典，并且每个条目将一个（字符串）名称映射到一个函数对象、类对象或字符串。从 M.__test__ 中找到的函数和类对象的文档字符串会被搜索，字符串则被视为文档字符串。在输出中，M.__test__ 中的键 K 将以名称 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 shell。
>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
... print("yes")
... else:
... print("no")
... print("NO")
... print("NO!!!")
...
no
NO
NO!!!
>>>
任何预期输出都必须紧跟在包含代码的最后一个 '>>> ' 或 '... ' 行之后，并且预期输出（如果有）会延伸到下一个 '>>> ' 或全空白行。
细则
预期输出不能包含全空白行，因为这样的行被视为表示预期输出的结束。如果预期输出确实包含空行，请在您期望出现空行的 doctest 示例中放置
<BLANKLINE>。所有硬制表符都会使用 8 列制表位扩展为空格。由测试代码生成的输出中的制表符不会被修改。因为示例输出中的任何硬制表符都会被展开，这意味着如果代码输出包含硬制表符，则 doctest 能够通过的唯一方法是
NORMALIZE_WHITESPACE选项或 指令 生效。或者，可以重写测试以捕获输出，并将其与测试的一部分的期望值进行比较。在试错法中得出了这种处理源代码中制表符的方法，并且已被证明是处理制表符的最不容易出错的方法。可以通过编写自定义的DocTestParser类来使用不同的算法来处理制表符。标准输出的输出会被捕获，但不会捕获标准错误的输出（异常回溯通过不同的方式捕获）。
如果您在交互式会话中通过反斜杠继续一行，或者出于任何其他原因使用反斜杠，则应使用原始文档字符串，这将完全保留您键入的反斜杠
>>> 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
如果引发 ValueError，并且显示了 list.remove(x): x not in list 详细信息，则该 doctest 成功。
异常的预期输出必须以回溯头开始，回溯头可以是以下两行中的任一行，缩进与示例的第一行相同
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，或者如果该示例仅打印该回溯文本，都将通过。在实践中，普通输出很少以回溯标题行开头，因此这不会造成实际问题。回溯堆栈的每一行（如果存在）都必须比示例的第一行缩进更多，或者以非字母数字字符开头。回溯标题之后的第一个与标题缩进相同并以字母数字开头的行被视为异常详细信息的开始。当然，这对于真正的回溯是正确的。
当指定
IGNORE_EXCEPTION_DETAILdoctest 选项时，最左边的冒号之后的所有内容以及异常名称中的任何模块信息都将被忽略。交互式 shell 会省略某些
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 指令 中使用，并且可以通过 -o 选项传递给 doctest 命令行界面。
3.4 版本新增: -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: 3*14，则期望ValueError: 42的示例将通过，但如果引发例如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)¶
使用给定的名称创建一个新的选项标志，并返回新标志的整数值。当子类化
OutputChecker或DocTestRunner以创建你的子类支持的新选项时，可以使用register_optionflag()。register_optionflag()应始终使用以下惯用法调用MY_FLAG = register_optionflag('MY_FLAG')
指令¶
Doctest 指令可以用来修改单个示例的选项标志。Doctest 指令是示例源代码之后的特殊 Python 注释。
directive ::= "#" "doctest:"directive_optionsdirective_options ::=directive_option(","directive_option)* directive_option ::=on_or_offdirective_option_nameon_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
简单的分数也更容易让人理解，这使得文档更加出色。
基本 API¶
函数 testmod() 和 testfile() 为 doctest 提供了一个简单的接口，对于大多数基本用法应该足够了。有关这两个函数的非正式介绍，请参见 简单用法：检查文档字符串中的示例 和 简单用法：检查文本文件中的示例。
- doctest.testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None)¶
除了 *filename* 之外的所有参数都是可选的，并且应该以关键字形式指定。
测试名为 *filename* 的文件中的示例。返回
(failure_count, test_count)。可选参数 *module_relative* 指定如何解释文件名
如果 *module_relative* 为
True(默认值)，则 *filename* 指定一个与操作系统无关的模块相对路径。默认情况下，此路径相对于调用模块的目录；但是，如果指定了 *package* 参数，则该路径相对于该包。为了确保操作系统独立性，*filename* 应该使用/字符来分隔路径段，并且不能是绝对路径（即，它不能以/开头）。如果 *module_relative* 为
False，则 *filename* 指定一个与操作系统相关的路径。该路径可以是绝对路径或相对路径；相对路径是相对于当前工作目录解析的。
可选参数 *name* 给出了测试的名称；默认情况下，或如果为
None，则使用os.path.basename(filename)。可选参数 *package* 是一个 Python 包或 Python 包的名称，该包的目录应该用作模块相对文件名的基本目录。如果未指定包，则调用模块的目录将用作模块相对文件名的基本目录。如果 *module_relative* 为
False，则指定 *package* 是错误的。可选参数 *globs* 给出了一个字典，在执行示例时用作全局变量。为 doctest 创建此字典的新浅拷贝，以便其示例从一个干净的状态开始。默认情况下，或如果为
None，则使用一个新的空字典。可选参数 *extraglobs* 给出了一个合并到用于执行示例的全局变量中的字典。它的工作方式类似于
dict.update()：如果 *globs* 和 *extraglobs* 有一个公共键，则 *extraglobs* 中关联的值将出现在组合字典中。默认情况下，或如果为None，则不使用额外的全局变量。这是一个高级功能，允许 doctest 的参数化。例如，可以为基类编写 doctest，使用类的通用名称，然后通过传递一个将通用名称映射到要测试的子类的 *extraglobs* 字典来重用它以测试任意数量的子类。如果为 true，则可选参数 *verbose* 会打印大量内容，如果为 false，则仅打印失败；默认情况下，或如果为
None，则当且仅当'-v'在sys.argv中时，它才为 true。当为 true 时，可选参数 *report* 会在末尾打印摘要，否则在末尾不打印任何内容。在 verbose 模式下，摘要是详细的，否则摘要非常简短（事实上，如果所有测试都通过，则为空）。
可选参数 *optionflags*（默认值为 0）采用选项标志的按位或。请参见选项标志部分。
可选参数 *raise_on_error* 默认为 false。如果为 true，则在示例中第一次失败或出现意外异常时会引发异常。这允许在事后调试失败。默认行为是继续运行示例。
可选参数 *parser* 指定一个
DocTestParser(或子类)，该类应用于从文件中提取测试。它默认为一个普通的解析器（即，DocTestParser()）。可选参数 *encoding* 指定一个应该用于将文件转换为 Unicode 的编码。
- doctest.testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)¶
所有参数都是可选的，除了 *m* 之外的所有参数都应该以关键字形式指定。
测试从模块 *m* (或如果未提供 *m* 或为
None，则为模块__main__) 可访问的函数和类中的文档字符串中的示例，从m.__doc__开始。还会测试字典
m.__test__中可访问的示例（如果存在）。m.__test__将名称（字符串）映射到函数、类和字符串；会搜索函数和类的文档字符串中的示例；字符串则直接搜索，就像它们是文档字符串一样。只搜索附加到模块 m 的对象的文档字符串。
返回
(failure_count, test_count)。可选参数 name 给出模块的名称；默认情况下，或者如果为
None，则使用m.__name__。可选参数 exclude_empty 默认为 false。如果为 true，则会排除未找到 doctest 的对象。默认值是为了向后兼容，以便仍然使用
doctest.master.summarize结合testmod()的代码仍然可以为没有测试的对象获取输出。较新的DocTestFinder构造函数的 exclude_empty 参数默认为 true。可选参数 extraglobs、verbose、report、optionflags、raise_on_error 和 globs 与上面的函数
testfile()相同，只是 globs 默认为m.__dict__。
- doctest.run_docstring_examples(f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0)¶
测试与对象 f 相关的示例；例如，f 可以是字符串、模块、函数或类对象。
字典参数 globs 的浅拷贝用于执行上下文。
可选参数 name 用于失败消息，默认为
"NoName"。如果可选参数 verbose 为 true，则即使没有失败也会生成输出。默认情况下，仅在示例失败时才生成输出。
可选参数 compileflags 给出了 Python 编译器在运行示例时应使用的标志集。默认情况下，或者如果为
None，则会推导出与 globs 中找到的未来特性集相对应的标志。可选参数 optionflags 的作用与上面的函数
testfile()相同。
Unittest API¶
随着 doctest 模块集合的增长，您需要一种系统地运行所有 doctest 的方法。doctest 提供了两个函数，可用于从包含 doctest 的模块和文本文件创建 unittest 测试套件。要与 unittest 测试发现集成，请在测试模块中包含 load_tests 函数。
import unittest
import doctest
import my_module_with_doctests
def load_tests(loader, tests, ignore):
tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
return tests
有两个主要函数用于从文本文件和包含 doctest 的模块创建 unittest.TestSuite 实例。
- doctest.DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)¶
将一个或多个文本文件中的 doctest 测试转换为
unittest.TestSuite。返回的
unittest.TestSuite由 unittest 框架运行，并运行每个文件中的交互式示例。如果任何文件中的示例失败，则合成的单元测试将失败，并引发failureException异常，其中显示包含测试的文件名称和（有时是近似的）行号。如果跳过文件中的所有示例，则合成的单元测试也会标记为已跳过。将一个或多个路径（作为字符串）传递给要检查的文本文件。
可以提供选项作为关键字参数
可选参数 module_relative 指定应如何解释 paths 中的文件名。
如果 module_relative 为
True（默认值），则 paths 中的每个文件名都指定一个与操作系统无关的模块相对路径。默认情况下，此路径相对于调用模块的目录；但是，如果指定了 package 参数，则它相对于该包。为了确保与操作系统无关，每个文件名应使用/字符分隔路径段，并且不能是绝对路径（即，它不能以/开头）。如果 module_relative 为
False，则 paths 中的每个文件名都指定一个与操作系统相关的路径。该路径可以是绝对路径或相对路径；相对路径相对于当前工作目录解析。
可选参数 package 是一个 Python 包或 Python 包的名称，该包的目录应作为 paths 中模块相对文件名的基本目录。如果未指定包，则调用模块的目录将用作模块相对文件名的基本目录。如果 module_relative 为
False，则指定 package 是错误的。可选参数 setUp 指定测试套件的设置函数。在运行每个文件中的测试之前调用此函数。setUp 函数将传递一个
DocTest对象。setUp 函数可以访问作为传递的测试的 globs 属性的测试全局变量。可选参数 tearDown 指定测试套件的拆卸函数。在运行每个文件中的测试之后调用此函数。tearDown 函数将传递一个
DocTest对象。setUp 函数可以访问作为传递的测试的 globs 属性的测试全局变量。可选参数 globs 是一个字典，其中包含测试的初始全局变量。为每个测试创建一个此字典的新副本。默认情况下，globs 是一个新的空字典。
可选参数 optionflags 指定测试的默认 doctest 选项，通过将各个选项标志进行或运算来创建。请参阅 选项标志 部分。有关设置报告选项的更好方法，请参阅下面的函数
set_unittest_reportflags()。可选参数 *parser* 指定一个
DocTestParser(或子类)，该类应用于从文件中提取测试。它默认为一个普通的解析器（即，DocTestParser()）。可选参数 *encoding* 指定一个应该用于将文件转换为 Unicode 的编码。
全局
__file__将添加到使用DocFileSuite()从文本文件加载的 doctest 的全局变量中。
- doctest.DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, optionflags=0, checker=None)¶
将模块的 doctest 测试转换为
unittest.TestSuite。返回的
unittest.TestSuite将由 unittest 框架运行，并运行模块中的每个 doctest。如果任何 doctest 失败，则合成的单元测试将失败，并引发一个failureException异常，显示包含测试的文件名和（有时是近似的）行号。如果 docstring 中的所有示例都被跳过，则合成的单元测试也会被标记为已跳过。可选参数 module 提供要测试的模块。它可以是一个模块对象或一个（可能是点分隔的）模块名称。如果未指定，则使用调用此函数的模块。
可选参数 globs 是一个字典，其中包含测试的初始全局变量。为每个测试创建一个此字典的新副本。默认情况下，globs 是一个新的空字典。
可选参数 extraglobs 指定一组额外的全局变量，这些变量将合并到 globs 中。默认情况下，不使用额外的全局变量。
可选参数 test_finder 是用于从模块中提取 doctest 的
DocTestFinder对象（或可替代的替代品）。可选参数 setUp、tearDown 和 optionflags 与上面的
DocFileSuite()函数相同。此函数使用与
testmod()相同的搜索技术。在 3.5 版本中更改: 如果 module 不包含 docstring，
DocTestSuite()将返回一个空的unittest.TestSuite，而不是引发ValueError。
- exception doctest.failureException¶
当通过
DocFileSuite()或DocTestSuite()转换为单元测试的 doctest 失败时，将引发此异常，显示包含测试的文件名和（有时是近似的）行号。
在底层，DocTestSuite() 从 doctest.DocTestCase 实例创建一个 unittest.TestSuite，而 DocTestCase 是 unittest.TestCase 的子类。DocTestCase 在这里没有文档记录（它是一个内部细节），但是研究它的代码可以回答有关 unittest 集成的确切细节的问题。
类似地，DocFileSuite() 从 doctest.DocFileCase 实例创建一个 unittest.TestSuite，而 DocFileCase 是 DocTestCase 的子类。
因此，创建 unittest.TestSuite 的两种方式都会运行 DocTestCase 的实例。这对于一个微妙的原因很重要：当您自己运行 doctest 函数时，您可以通过将选项标志传递给 doctest 函数来直接控制使用的 doctest 选项。但是，如果您正在编写 unittest 框架，unittest 最终控制何时以及如何运行测试。框架作者通常希望控制 doctest 报告选项（例如，可能由命令行选项指定），但是没有办法通过 unittest 将选项传递给 doctest 测试运行器。
因此，doctest 还支持一个特定于 unittest 支持的 doctest 报告标志的概念，通过此函数
- doctest.set_unittest_reportflags(flags)¶
设置要使用的
doctest报告标志。参数 flags 接受选项标志的 按位或。请参阅 选项标志 部分。只能使用“报告标志”。
这是一个模块全局设置，会影响模块
unittest运行的所有未来 doctest：DocTestCase的runTest()方法会查看构造DocTestCase实例时为测试用例指定的选项标志。如果没有指定报告标志（这是典型和预期的情况），则doctest的unittest报告标志会 按位或 到选项标志中，并且将如此扩充的选项标志传递给创建用于运行 doctest 的DocTestRunner实例。如果在构造DocTestCase实例时指定了任何报告标志，则doctest的unittest报告标志将被忽略。函数返回函数调用之前生效的
unittest报告标志的值。
高级 API¶
基本 API 是一个简单的包装器，旨在使 doctest 易于使用。它相当灵活，应该满足大多数用户的需求；但是，如果您需要对测试进行更细粒度的控制，或者希望扩展 doctest 的功能，则应使用高级 API。
高级 API 围绕两个容器类展开，这两个容器类用于存储从 doctest 用例中提取的交互式示例
定义了其他处理类来查找、解析、运行和检查 doctest 示例
DocTestFinder: 查找给定模块中的所有 docstring，并使用DocTestParser从每个包含交互式示例的 docstring 创建一个DocTest。DocTestParser: 从字符串（例如对象的 docstring）创建一个DocTest对象。DocTestRunner: 执行DocTest中的示例，并使用OutputChecker验证其输出。OutputChecker: 将 doctest 示例的实际输出与预期输出进行比较，并确定它们是否匹配。
这些处理类之间的关系总结在以下图中
list of:
+------+ +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+ | ^ +---------+ | ^ (printed)
| | | Example | | |
v | | ... | v |
DocTestParser | Example | OutputChecker
+---------+
DocTest 对象¶
Example 对象¶
- class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)¶
单个交互式示例，由一个 Python 语句及其预期输出组成。构造函数的参数用于初始化同名的属性。
Example定义以下属性。它们由构造函数初始化，不应直接修改。- source¶
一个包含示例源代码的字符串。此源代码由单个 Python 语句组成，并且始终以换行符结尾；构造函数在必要时会添加换行符。
- 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* 指定用于从文档字符串中提取 doctest 的
DocTestParser对象（或直接替换）。如果可选参数 *recurse* 为 false，则
DocTestFinder.find()将仅检查给定对象，而不检查任何包含的对象。如果可选参数 *exclude_empty* 为 false，则
DocTestFinder.find()将包含具有空文档字符串的对象的测试。DocTestFinder定义以下方法- find(obj[, name][, module][, globs][, extraglobs])¶
返回由 *obj* 的文档字符串或其任何包含对象的文档字符串定义的
DocTest的列表。可选参数 *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的文档。
TestResults 对象¶
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 是包含示例的测试。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 的 future-import 标志集。
每个示例的输出都使用
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)¶
当示例的实际输出 (got) 与预期输出 (want) 匹配时，返回
True。如果这些字符串相同，则始终认为它们匹配；但是，根据测试运行程序正在使用的选项标志，也可能存在几种非完全匹配类型。有关选项标志的更多信息，请参见 选项标志 部分。
- output_difference(example, got, optionflags)¶
返回一个字符串，描述给定示例的预期输出 (example) 与实际输出 (got) 之间的差异。optionflags 是用于比较 want 和 got 的选项标志集。
调试¶
Doctest 提供了几种用于调试 doctest 示例的机制
多个函数将 doctest 转换为可执行的 Python 程序，这些程序可以在 Python 调试器
pdb下运行。DebugRunner类是DocTestRunner的子类，它会为第一个失败的示例引发异常，其中包含有关该示例的信息。此信息可用于对示例执行事后调试。由
DocTestSuite()生成的unittest用例支持debug()方法，该方法由unittest.TestCase定义。您可以在 doctest 示例中添加对
pdb.set_trace()的调用，当执行该行时，您将进入 Python 调试器。然后，您可以检查变量的当前值，等等。例如，假设a.py只包含此模块文档字符串""" >>> def f(x): ... g(x*2) >>> def g(x): ... print(x+3) ... import pdb; pdb.set_trace() >>> f(3) 9 """
然后，交互式 Python 会话可能如下所示
>>> import a, doctest >>> doctest.testmod(a) --Return-- > <doctest a[1]>(3)g()->None -> import pdb; pdb.set_trace() (Pdb) list 1 def g(x): 2 print(x+3) 3 -> import pdb; pdb.set_trace() [EOF] (Pdb) p x 6 (Pdb) step --Return-- > <doctest a[0]>(2)f()->None -> g(x*2) (Pdb) list 1 def f(x): 2 -> g(x*2) [EOF] (Pdb) p x 3 (Pdb) step --Return-- > <doctest a[2]>(1)?()->None -> f(3) (Pdb) cont (0, 3) >>>
将 doctest 转换为 Python 代码的函数，并可能在调试器下运行合成代码
- doctest.script_from_examples(s)¶
将带有示例的文本转换为脚本。
参数 s 是一个包含 doctest 示例的字符串。该字符串被转换为 Python 脚本，其中 s 中的 doctest 示例被转换为常规代码，而其他所有内容都被转换为 Python 注释。生成的脚本以字符串形式返回。例如，
import doctest print(doctest.script_from_examples(r""" Set x and y to 1 and 2. >>> x, y = 1, 2 Print their sum: >>> print(x+y) 3 """))
显示
# Set x and y to 1 and 2. x, y = 1, 2 # # Print their sum: print(x+y) # Expected: ## 3
此函数在内部供其他函数使用（请参见下文），但当您想将交互式 Python 会话转换为 Python 脚本时也很有用。
- doctest.testsource(module, name)¶
将对象的 doctest 转换为脚本。
参数 module 是一个模块对象，或模块的点分名称，其中包含需要进行 doctest 的对象。参数 name 是（模块内）需要进行 doctest 的对象的名称。结果是一个字符串，包含对象的文档字符串，该字符串已转换为 Python 脚本，如上文
script_from_examples()中所述。例如，如果模块a.py包含一个顶层函数f()，那么import a, doctest print(doctest.testsource(a, "a.f"))
将打印函数
f()的文档字符串的脚本版本，其中 doctest 已转换为代码，其余部分放在注释中。
- doctest.debug(module, name, pm=False)¶
调试对象的 doctest。
module 和 name 参数与上述函数
testsource()中的参数相同。为命名对象的文档字符串合成的 Python 脚本将写入临时文件，然后该文件将在 Python 调试器pdb的控制下运行。module.__dict__的浅拷贝将用于局部和全局执行上下文。可选参数 pm 控制是否使用事后调试。如果 pm 的值为 true，则脚本文件将直接运行，并且只有当脚本通过引发未处理的异常而终止时，调试器才会介入。如果确实发生了这种情况，则会通过
pdb.post_mortem()调用事后调试，并传递来自未处理异常的回溯对象。如果未指定 pm 或 pm 为 false，则脚本将从一开始就在调试器下运行，方法是将适当的exec()调用传递给pdb.run()。
- doctest.debug_src(src, pm=False, globs=None)¶
调试字符串中的 doctest。
这类似于上面的函数
debug()，只是通过 src 参数直接指定了包含 doctest 示例的字符串。可选参数 pm 的含义与上述函数
debug()中的含义相同。可选参数 globs 提供一个字典，用作局部和全局执行上下文。如果未指定，或为
None，则使用空字典。如果指定，则使用字典的浅拷贝。
DebugRunner 类以及它可能引发的特殊异常，对测试框架的作者最感兴趣，并且这里仅作简要介绍。有关更多详细信息，请参阅源代码，尤其是 DebugRunner 的文档字符串（这是一个 doctest！）。
- class doctest.DebugRunner(checker=None, verbose=None, optionflags=0)¶
DocTestRunner的子类，一旦遇到故障就会引发异常。如果发生意外异常，则会引发UnexpectedException异常，其中包含测试、示例和原始异常。如果输出不匹配，则会引发DocTestFailure异常，其中包含测试、示例和实际输出。有关构造函数参数和方法的信息，请参阅
DocTestRunner在 高级 API 部分的文档。
DebugRunner 实例可能会引发两个异常
- exception doctest.DocTestFailure(test, example, got)¶
DocTestRunner引发的异常，用于指示 doctest 示例的实际输出与其预期输出不匹配。构造函数参数用于初始化具有相同名称的属性。
DocTestFailure 定义以下属性
- DocTestFailure.got¶
示例的实际输出。
- exception doctest.UnexpectedException(test, example, exc_info)¶
DocTestRunner引发的异常，用于指示 doctest 示例引发了意外异常。构造函数参数用于初始化具有相同名称的属性。
UnexpectedException 定义以下属性
- UnexpectedException.exc_info¶
一个元组，包含有关意外异常的信息，如
sys.exc_info()返回的那样。
随想录¶
如简介中所述，doctest 的用途已扩展到三个主要方面
检查文档字符串中的示例。
回归测试。
可执行文档/文学化测试。
这些用途具有不同的要求，区分它们非常重要。特别是，在文档字符串中填充晦涩的测试用例会使文档变得糟糕。
编写文档字符串时，请谨慎选择文档字符串示例。这其中蕴含着一种需要学习的技巧，起初可能不那么自然。示例应该为文档增加真正的价值。一个好的示例通常胜过千言万语。如果用心编写，这些示例对于您的用户将是宝贵的，并且随着时间的推移和事物的变化，它们会多次回报您收集它们所花费的时间。我仍然惊讶于我的 doctest 示例在一次“无害”的更改后停止工作的情况是多么频繁。
Doctest 也是一个优秀的回归测试工具，尤其是在您不吝啬解释性文本的情况下。通过交错散文和示例，可以更容易地跟踪实际测试的内容以及原因。当测试失败时，好的散文可以更容易地找出问题所在以及应该如何修复。诚然，您可以在基于代码的测试中编写大量的注释，但很少有程序员这样做。许多人发现，使用 doctest 方法反而会产生更清晰的测试。也许这仅仅是因为 doctest 使编写散文比编写代码更容易一些，而编写代码中的注释则稍微困难一些。我认为这不仅仅如此：编写基于 doctest 的测试时的自然态度是您想要解释软件的精妙之处，并用示例来说明它们。这反过来自然而然地导致测试文件从最简单的功能开始，并逻辑地发展到复杂情况和边缘情况。结果是一个连贯的叙述，而不是一个看似随机地测试孤立功能片段的孤立函数集合。这是一种不同的态度，并产生不同的结果，模糊了测试和解释之间的区别。
回归测试最好限制在专用对象或文件中。有几种组织测试的选项
编写包含交互式示例的测试用例的文本文件，并使用
testfile()或DocFileSuite()测试这些文件。这是推荐的做法，但对于从一开始就设计为使用 doctest 的新项目来说最容易做到。定义名为
_regrtest_topic的函数，这些函数由包含命名主题的测试用例的单个文档字符串组成。这些函数可以包含在与模块相同的文件中，也可以分离到单独的测试文件中。定义一个
__test__字典，将回归测试主题映射到包含测试用例的文档字符串。
当您将测试放置在模块中时，该模块本身就可以成为测试运行器。当测试失败时，您可以安排测试运行器仅重新运行失败的 doctest，以便您调试问题。这是一个这样的测试运行器的最小示例
if __name__ == '__main__':
import doctest
flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
if len(sys.argv) > 1:
name = sys.argv[1]
if name in globals():
obj = globals()[name]
else:
obj = __test__[name]
doctest.run_docstring_examples(obj, globals(), name=name,
optionflags=flags)
else:
fail, total = doctest.testmod(optionflags=flags)
print(f"{fail} failures out of {total} tests")
脚注