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 tests in __main__
8 tests in __main__.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$
这就是开始有效使用 doctest 所需的全部知识！开始吧。以下部分提供了完整的详细信息。请注意，标准 Python 测试套件和库中有许多 doctest 示例。特别有用的示例可以在标准测试文件 Lib/test/test_doctest/test_doctest.py 中找到。
简单用法：检查文档字符串中的示例¶
开始使用 doctest 的最简单方法（但不一定是您将继续使用的方法）是以
if __name__ == "__main__":
import doctest
doctest.testmod()
结束每个模块 M，然后 doctest 会检查模块 M 中的文档字符串。
将模块作为脚本运行会导致执行和验证文档字符串中的示例
python M.py
除非示例失败，否则这不会显示任何内容，在这种情况下，失败的示例和失败的原因将打印到标准输出，并且最后一行输出为 ***测试 失败*** N 次失败。，其中 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() 相同的格式打印到标准输出。
默认情况下，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类来使用不同的算法来处理制表符。将捕获到 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
如果引发 ValueError，则该 doctest 将成功，并显示 list.remove(x): x not in list 详细信息。
异常的预期输出必须以回溯标头开头，该标头可以是以下两行中的任何一行，缩进与示例的第一行相同
Traceback (most recent call last):
Traceback (innermost last):
回溯标头后面跟着一个可选的回溯堆栈，其内容被 doctest 忽略。回溯堆栈通常被省略，或者从交互式会话中逐字复制。
回溯堆栈后面跟着最有趣的部分：包含异常类型和详细信息的行。这通常是回溯的最后一行，但如果异常有多行详细信息，则可以跨越多行
>>> raise ValueError('multi\n line\ndetail')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: multi
line
detail
最后三行（从 ValueError 开始）将与异常的类型和详细信息进行比较，其余部分将被忽略。
最佳做法是省略回溯堆栈，除非它为示例添加了重要的文档价值。所以最后一个例子可能更好
>>> raise ValueError('multi\n line\ndetail')
Traceback (most recent call last):
...
ValueError: multi
line
detail
请注意，回溯的处理方式非常特殊。特别是，在重写的示例中，... 的使用独立于 doctest 的 ELLIPSIS 选项。该示例中的省略号可以省略，也可以是三个（或三百个）逗号或数字，或者 Monty Python 短剧的缩进脚本。
您应该阅读一次但无需记住的一些细节
Doctest 无法猜测您的预期输出是来自异常回溯还是来自普通打印。因此，例如，一个预期输出为
ValueError: 42 is prime的示例，无论是否实际引发了ValueError，或者示例是否仅打印了该回溯文本，该示例都将通过。在实践中，普通输出很少以回溯标头行开头，因此这不会造成实际问题。回溯堆栈的每一行（如果存在）都必须比示例的第一行缩进更多，*或者*以非字母数字字符开头。回溯标头后面跟着的第一行缩进相同并且以字母数字开头，则被视为异常详细信息的开头。当然，这对于真正的回溯来说是正确的。
指定
IGNORE_EXCEPTION_DETAILdoctest 选项后，最左侧冒号后面的所有内容以及异常名称中的任何模块信息都将被忽略。对于某些
SyntaxError，交互式 shell 会省略回溯标题行。但 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 字典来重用它以测试任意数量的子类。可选参数 verbose 如果为 true，则会打印大量信息，如果为 false，则仅打印失败信息；默认情况下，或者如果为
None，则当且仅当'-v'在sys.argv中时才为 true。可选参数 report 如果为 true，则在结束时打印摘要，否则在结束时不打印任何内容。在详细模式下，摘要将非常详细，否则摘要将非常简短（实际上，如果所有测试都通过，则为空）。
可选参数 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 或 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()相同。
单元测试 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异常，显示包含测试的文件名和（有时是近似的）行号。可选参数 module 提供要测试的模块。它可以是模块对象或（可能带点的）模块名称。如果未指定，则使用调用此函数的模块。
可选参数 globs 是一个字典，包含测试的初始全局变量。将为每个测试创建此字典的新副本。默认情况下，globs 是一个新的空字典。
可选参数 extraglobs 指定一组额外的全局变量，这些变量将合并到 globs 中。默认情况下，不使用额外的全局变量。
可选参数 test_finder 是用于从模块中提取 doctest 的
DocTestFinder对象（或替代品）。可选参数 setUp、tearDown 和 optionflags 与上面
DocFileSuite()函数中的相同。此函数使用与
testmod()相同的搜索技术。在 3.5 版更改: 如果 module 不包含任何文档字符串，则
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：runTest()方法DocTestCase查看在构造DocTestCase实例时为测试用例指定的选项标志。如果未指定报告标志（这是典型且预期的情况），则doctest的unittest报告标志将与选项标志进行 按位或 运算，并将如此增强的选项标志传递给为运行 doctest 而创建的DocTestRunner实例。如果在构造DocTestCase实例时指定了任何报告标志，则将忽略doctest的unittest报告标志。该函数返回调用该函数之前生效的
unittest报告标志的值。
高级 API¶
基本 API 是一个简单的包装器，旨在使 doctest 易于使用。它相当灵活，应该可以满足大多数用户的需求；但是，如果您需要对测试进行更精细的控制，或者希望扩展 doctest 的功能，那么您应该使用高级 API。
高级 API 围绕两个容器类构建，这两个容器类用于存储从 doctest 案例中提取的交互式示例
定义了其他处理类来查找、解析、运行和检查 doctest 示例
DocTestFinder：查找给定模块中的所有文档字符串，并使用DocTestParser从包含交互式示例的每个文档字符串创建一个DocTest。DocTestParser：从字符串（例如对象的文档字符串）创建DocTest对象。DocTestRunner：执行DocTest中的示例，并使用OutputChecker验证其输出。OutputChecker：将 doctest 示例的实际输出与预期输出进行比较，并确定它们是否匹配。
这些处理类之间的关系总结在下图中
list of:
+------+ +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+ | ^ +---------+ | ^ (printed)
| | | Example | | |
v | | ... | v |
DocTestParser | Example | OutputChecker
+---------+
DocTest 对象¶
示例对象¶
- 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的文档。
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 指定应用于将预期输出与 doctest 示例的实际输出进行比较的
OutputChecker对象（或直接替换）。可选关键字参数 verbose 控制
DocTestRunner的详细程度。如果 verbose 为True，则会打印有关每个示例的信息，因为它正在运行。如果 verbose 为False，则仅打印失败。如果未指定 verbose 或为None，则仅当使用命令行开关-v时才使用详细输出。可选关键字参数 optionflags 可用于控制测试运行器如何将预期输出与实际输出进行比较，以及如何显示失败。有关更多信息，请参阅 选项标志 部分。
DocTestRunner定义了以下方法- report_start(out, test, example)¶
报告测试运行器即将处理给定的示例。提供此方法是为了允许
DocTestRunner的子类自定义其输出；不应直接调用它。example 是即将处理的示例。 test 是*包含示例*的测试。 out 是传递给
DocTestRunner.run()的输出函数。
- report_success(out, test, example, got)¶
报告给定的示例已成功运行。提供此方法是为了允许
DocTestRunner的子类自定义其输出；不应直接调用它。example 是即将处理的示例。 got 是示例的实际输出。 test 是*包含示例*的测试。 out 是传递给
DocTestRunner.run()的输出函数。
- report_failure(out, test, example, got)¶
报告给定的示例失败。提供此方法是为了允许
DocTestRunner的子类自定义其输出；不应直接调用它。example 是即将处理的示例。 got 是示例的实际输出。 test 是*包含示例*的测试。 out 是传递给
DocTestRunner.run()的输出函数。
- report_unexpected_exception(out, test, example, exc_info)¶
报告给定的示例引发了意外异常。提供此方法是为了允许
DocTestRunner的子类自定义其输出；不应直接调用它。example 是即将处理的示例。 exc_info 是一个包含有关意外异常的信息的元组（由
sys.exc_info()返回）。 test 是*包含示例*的测试。 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)¶
当且仅当示例的实际输出 (got) 与预期输出 (want) 匹配时，返回
True。如果这两个字符串完全相同，则始终认为它们匹配；但根据测试运行程序使用的选项标志，也可能存在几种不完全匹配的类型。有关选项标志的更多信息，请参阅 选项标志 部分。
- output_difference(example, got, optionflags)¶
返回一个字符串，描述给定示例 (example) 的预期输出与实际输出 (got) 之间的差异。 optionflags 是用于比较 want 和 got 的选项标志集。
调试¶
Doctest 提供了几种调试 doctest 示例的机制
有几个函数可以将 doctest 转换为可执行的 Python 程序，这些程序可以在 Python 调试器
pdb下运行。DebugRunner类是DocTestRunner的子类，它会为第一个失败的示例引发异常，其中包含有关该示例的信息。此信息可用于对示例执行事后调试。DocTestSuite()生成的unittest测试用例支持unittest.TestCase定义的debug()方法。您可以在 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 为真值，则直接运行脚本文件，并且只有当脚本通过引发未处理的异常终止时，调试器才会介入。如果是这样，则通过
pdb.post_mortem()调用事后调试，并传递来自未处理异常的回溯对象。如果未指定 pm 或为假，则通过将适当的exec()调用传递给pdb.run()，从一开始就在调试器下运行脚本。
- doctest.debug_src(src, pm=False, globs=None)¶
调试字符串中的 doctest。
这类似于上面的
debug()函数，不同之处在于，包含 doctest 示例的字符串是通过 *src* 参数直接指定的。可选参数 *pm* 的含义与上面
debug()函数中的含义相同。可选参数 *globs* 提供了一个字典，用作本地和全局执行上下文。如果未指定或为
None，则使用空字典。如果指定，则使用字典的浅拷贝。
DebugRunner 类及其可能引发的特殊异常主要供测试框架作者使用，这里只做简要介绍。有关更多详细信息，请参阅源代码，尤其是 DebugRunner 的文档字符串（它本身就是一个 doctest！）
- class doctest.DebugRunner(checker=None, verbose=None, optionflags=0)¶
DocTestRunner的子类，一旦遇到失败就会引发异常。如果发生意外异常，则会引发UnexpectedException异常，其中包含测试、示例和原始异常。如果输出不匹配，则会引发DocTestFailure异常，其中包含测试、示例和实际输出。有关构造函数参数和方法的信息，请参阅 高级 API 部分中
DocTestRunner的文档。
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()返回。
Soapbox¶
如介绍中所述，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("{} failures out of {} tests".format(fail, total))
脚注