Python标准库doctest测试交互性的Python示例

哪些文件串被检查了？¶

模块的文档串以及所有函数、类和方法的文档串都将被搜索。 导入模块的对象不被搜索。

此外，如果 M.__test__ 存在并且 "为真值"，则它必须是一个字典，其中每个条目都将一个（字符串）名称映射到一个函数对象、类对象或字符串。 从 M.__test__ 找到的函数和类对象的文档字符串会被搜索，而字符串会被当作文档字符串来处理。 在输出时，每个键 K 在 M.__test__ 中都显示为其名称

<nameofM>.__test__.K

任何发现的类都会以类似的方式进行递归搜索，以测试其包含的方法和嵌套类中的文档串。

文档串的例子是如何被识别的？¶

在大多数情况下，对交互式控制台会话的复制和粘贴功能工作得很好，但是 doctest 并不试图对任何特定的 Python shell 进行精确的模拟。

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

任何预期的输出必须紧随包含代码的最后 '>>>' 或 '...' 行，预期的输出（如果有的话）延伸到下一 '>>>' 行或全空白行。

fine输出：

• 预期输出不能包含一个全白的行，因为这样的行被认为是预期输出的结束信号。 如果预期的输出包含一个空行，在你的测试例子中，在每一个预期有空行的地方加上``<BLANKLINE>``。

• 所有硬制表符都被扩展为空格，使用 8 列的制表符。由测试代码生成的输出中的制表符不会被修改。 因为样本输出中的任何硬制表符都会被扩展，这意味着如果代码输出包括硬制表符，文档测试通过的唯一方法是 NORMALIZE_WHITESPACE 选项或者 指令 是有效的。 另外，测试可以被重写，以捕获输出并将其与预期值进行比较，作为测试的一部分。这种对源码中标签的处理是通过试错得出的，并被证明是最不容易出错的处理方式。通过编写一个自定义的 DocTestParser 类，可以使用一个不同的算法来处理标签。

• 向stdout的输出被捕获，但不向stderr输出（异常回溯通过不同的方式被捕获）。

• 如果你在交互式会话中通过反斜线续行，或出于任何其他原因使用反斜线，你应该使用原始文件串，它将完全保留你输入的反斜线:

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

  否则，反斜杠将被解释为字符串的一部分。例如，上面的``n``会被解释为一个换行符。 另外，你可以在doctest版本中把每个反斜杠加倍（而不使用原始字符串）:

  >>> deff(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() 来强制使用你自己的dict作为执行环境。

异常如何处理？¶

没问题，只要回溯是这个例子产生的唯一输出：只要粘贴回溯即可。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):xnotinlist 的细节如图所示。

异常的预期输出必须以回溯头开始，可以是以下两行中的任何一行，缩进程度与例子中的第一行相同:

Traceback(mostrecentcalllast):
Traceback(innermostlast):

回溯头的后面是一个可选的回溯堆栈，其内容被doctest忽略。 回溯堆栈通常是省略的，或者从交互式会话中逐字复制的。

回溯堆栈的后面是最有趣的部分：包含异常类型和细节的一行（几行）。 这通常是回溯的最后一行，但如果异常有多行细节，则可以延伸到多行:

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

最后三行（以 ValueError 开头）将与异常的类型和细节进行比较，其余的被忽略。

最佳实践是省略回溯栈，除非它为这个例子增加了重要的文档价值。 因此，最后一个例子可能更好，因为:

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

请注意，回溯的处理方式非常特别。 特别是，在重写的例子中，... 的使用与 doctest 的 ELLIPSIS 选项无关。 该例子中的省略号可以不写，也可以是三个（或三百个）逗号或数字，或者是一个缩进的 Monty Python 短剧的剧本。

有些细节你应该读一遍，但不需要记住：

• Doctest 不能猜测你的预期输出是来自异常回溯还是来自普通打印。 因此，例如，一个期望 ValueError:42isprime 的用例将通过测试，无论 ValueError 是真的被触发，或者该用例只是打印了该回溯文本。 在实践中，普通输出很少以回溯标题行开始，所以这不会产生真正的问题。

• 回溯堆栈的每一行（如果有的话）必须比例子的第一行缩进， 或者 以一个非字母数字的字符开始。 回溯头之后的第一行缩进程度相同，并且以字母数字开始，被认为是异常细节的开始。 当然，这对真正的回溯来说是正确的事情。

• 当 IGNORE_EXCEPTION_DETAIL doctest 选项被指定时，最左边的冒号后面的所有内容以及异常名称中的任何模块信息都被忽略。

• 交互式 shell 省略了一些 SyntaxError 的回溯头行。但 doctest 使用回溯头行来区分异常和非异常。所以在罕见的情况下，如果你需要测试一个省略了回溯头的 SyntaxError，你将需要手动添加回溯头行到你的测试用例中。

• 对于一些 SyntaxError，Python 使用 ^ 标记显示语法错误的字符位置:

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

  由于显示错误位置的行在异常类型和细节之前，它们不被doctest检查。 例如，下面的测试会通过，尽管它把``^``标记放在了错误的位置:

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

选项标记¶

一系列选项旗标控制着 doctest 的各方面行为。 旗标的符号名称以模块常量的形式提供，可以一起 按位或 并传递给各种函数。 这些名称也可以在 doctest 指令 中使用，并且可以通过 -o 选项传递给 doctest 命令行接口。

第一组选项定义了测试语义，控制doctest如何决定实际输出是否与用例的预期输出相匹配方面的问题。

doctest.DONT_ACCEPT_TRUE_FOR_1¶

默认情况下，如果一个预期的输出块只包含 1，那么实际的输出块只包含 1 或只包含 True 就被认为是匹配的，同样，0 与 False 也是如此。 当 DONT_ACCEPT_TRUE_FOR_1 被指定时，两种替换都不允许。 默认行为是为了适应 Python 将许多函数的返回类型从整数改为布尔值；期望 "小整数" 输出的测试在这些情况下仍然有效。 这个选项可能会消失，但不会在几年内消失。

doctest.DONT_ACCEPT_BLANKLINE¶

默认情况下，如果一个预期输出块包含一个只包含字符串 <BLANKLINE> 的行，那么该行将与实际输出中的一个空行相匹配。 因为一个真正的空行是对预期输出的限定，这是传达预期空行的唯一方法。 当 DONT_ACCEPT_BLANKLINE 被指定时，这种替换是不允许的。

doctest.NORMALIZE_WHITESPACE¶

当指定时，所有的空白序列（空白和换行）都被视为相等。预期输出中的任何空白序列将与实际输出中的任何空白序列匹配。默认情况下，空白必须完全匹配。 NORMALIZE_WHITESPACE 在预期输出非常长的一行，而你想把它包在源代码的多行中时特别有用。

doctest.ELLIPSIS¶

当指定时，预期输出中的省略号（...）可以匹配实际输出中的任何子串。这包括跨行的子串和空子串，所以最好保持简单的用法。复杂的用法会导致与``.*``在正则表达式中容易出现的 "oops, it matched too much!"相同的意外情况。

doctest.IGNORE_EXCEPTION_DETAIL¶

当被指定时，如果一个预期的异常类型被触发，即使异常细节不匹配，期望异常的用例也会通过。 例如，如果实际引发的异常是 ValueError:42，期待 ValueError:3*14 的用例将通过，但例如，如果 TypeError 触发将导致失败。

它也会忽略Python 3 doctest报告中使用的模块名称。因此，无论测试是在Python 2.7还是Python 3.2 (或更高版本)下运行，这两种变化都会在指定的标志下工作:

>>> raiseCustomError('message')
Traceback (most recent call last):
CustomError: message
>>> raiseCustomError('message')
Traceback (most recent call last):
my_module.CustomError: message

注意 ELLIPSIS 也可以用来忽略异常信息的细节，但这样的测试仍然可能失败，因为模块的细节可能被打印为异常名称的一部分。使用 IGNORE_EXCEPTION_DETAIL 和 Python 2.3 的细节也是唯一明确的方法，可以编写一个不关心异常细节但在 Python 2.3 或更早的版本中继续通过的 doctest (这些版本不支持 doctest directives 并将其作为无关的注释忽略)。例如:

>>> (1,2)[3]='moo'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: object doesn't support item assignment

在Python 2.3及以后的Python版本中，在指定了标志的情况下通过，尽管这个细节在Python 2.4中改变为 "does not" 而不是 "doesn't"。

在 3.2 版更改: IGNORE_EXCEPTION_DETAIL 现在也忽略了与包含被测异常的模块有关的任何信息。

doctest.SKIP¶

当指定时，完全不运行这个用例。 这在doctest用例既是文档又是测试案例的情况下很有用，一个例子应该包括在文档中，但不应该被检查。例如，这个例子的输出可能是随机的；或者这个例子可能依赖于测试驱动程序所不能使用的资源。

SKIP标志也可用于临时 "注释" 用例。

doctest.COMPARISON_FLAGS¶

一个比特或运算将上述所有的比较标志放在一起。

第二组选项控制测试失败的报告方式：

doctest.REPORT_UDIFF¶

当指定时，涉及多行预期和实际输出的故障将使用统一的差异来显示。

doctest.REPORT_CDIFF¶

当指定时，涉及多行预期和实际输出的故障将使用上下文差异来显示。

doctest.REPORT_NDIFF¶

当指定时，差异由``difflib.Differ``来计算，使用与流行的:file:ndiff.py`工具相同的算法。这是唯一一种标记行内和行间差异的方法。 例如，如果一行预期输出包含数字``1`，而实际输出包含字母``l``，那么就会插入一行，用圆点标记不匹配的列位置。

doctest.REPORT_ONLY_FIRST_FAILURE¶

当指定时，在每个 doctest 中显示第一个失败的用例，但隐藏所有其余用例的输出。 这将防止 doctest 报告由于先前的失败而中断的正确用例；但也可能隐藏独立于第一个失败的不正确用例。 当 REPORT_ONLY_FIRST_FAILURE 被指定时，其余的用例仍然被运行，并且仍然计入报告的失败总数；只是输出被隐藏了。

doctest.FAIL_FAST¶

当指定时，在第一个失败的用例后退出，不尝试运行其余的用例。因此，报告的失败次数最多为1。这个标志在调试时可能很有用，因为第一个失败后的用例甚至不会产生调试输出。

doctest命令行接受选项``-f``作为``-o FAIL_FAST``的简洁形式。

3.4 新版功能.

doctest.REPORTING_FLAGS¶

一个比特或操作将上述所有的报告标志组合在一起。

还有一种方法可以注册新的选项标志名称，不过这并不有用，除非你打算通过子类来扩展 doctest 内部。

doctest.register_optionflag(name)¶

用给定的名称创建一个新的选项标志，并返回新标志的整数值。 register_optionflag() 可以在继承 OutputChecker 或 DocTestRunner 时使用，以创建子类支持的新选项。 register_optionflag() 应始终使用以下方式调用:

MY_FLAG=register_optionflag('MY_FLAG')

指令¶

Doctest指令可以用来修改单个例子的 option flags 。 Doctest指令是在一个用例的源代码后面的特殊Python注释。

directive             ::=  "#" "doctest:" directive_options
directive_options     ::=  directive_option ("," directive_option)\*
directive_option      ::=  on_or_offdirective_option_name
on_or_off             ::=  "+" \| "-"
directive_option_name ::=  "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...

+ 或 - 与指令选项名称之间不允许有空格。 指令选项名称可以是上面解释的任何一个选项标志名称。

一个用例的 doctest 指令可以修改 doctest 对该用例的行为。 使用 + 来启用指定的行为，或者使用 - 来禁用它。

例如，这个测试将会通过:

>>> print(list(range(20)))
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

如果没有这个指令，它就会失败，这是因为实际的输出在个位数的列表元素前没有两个空格，也因为实际的输出是在单行上。 这个测试也通过了，而且也需要一个指令来完成:

>>> print(list(range(20)))
[0, 1, ..., 18, 19]

在一个物理行上可以使用多个指令，用逗号分隔:

>>> print(list(range(20)))
[0,    1, ...,   18,    19]

如果在一个用例中使用了多个指令注释，那么它们将被合并:

>>> print(list(range(20)))
... 
[0,    1, ...,   18,    19]

正如前面的例子所示，你可以在你的用例中添加只包含指令的行。 当一个用例太长，指令不能舒适地放在同一行时，这可能很有用:

>>> print(list(range(5))+list(range(10,20))+list(range(30,40)))
... 
[0, ..., 4, 10, ..., 19, 30, ..., 39]

请注意，由于所有的选项都是默认禁用的，而指令只适用于它们出现的用例，所以启用选项 (通过指令中的 +) 通常是唯一有意义的选择。 然而，选项标志也可以被传递给运行测试的函数，建立不同的默认值。 在这种情况下，通过指令中的 - 来禁用一个选项可能是有用的。

警告¶

doctest 是严格地要求在预期输出中完全匹配。 如果哪怕只有一个字符不匹配，测试就会失败。 这可能会让你吃惊几次，在你确切地了解到 Python 对输出的保证和不保证之前。 例如，当打印一个集合时，Python 不保证元素以任何特定的顺序被打印出来，所以像:

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

是不可靠的！一个变通方法是做:

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

来取代。另一个是使用

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

还有其他的问题，但你会明白的。

另一个不好的做法是打印嵌入了对象地址的变量，如:

>>> id(1.0)# certain to fail some of the time
7948648
>>> classC:pass
>>> C()# the default repr() for instances embeds an address
<__main__.C instance at 0x00AC18F0>

ELLIPSIS 指令为最后一个例子提供了一个不错的方法:

>>> C()
<__main__.C instance at 0x...>

浮点数在不同的平台上也会有小的输出变化，因为Python在浮点数的格式化上依赖于平台的C库，而C库在这个问题上的质量差异很大。:

>>> 1./7# risky
0.14285714285714285
>>> print(1./7)# safer
0.142857142857
>>> print(round(1./7,6))# much safer
0.142857

形式``I/2.**J``的数字在所有的平台上都是安全的，我经常设计一些测试的用例来产生该形式的数:

>>> 3./4# utterly safe
0.75

简单的分数也更容易让人理解，这也使得文件更加完善。

DocTest 对象¶

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

应该在单一命名空间中运行的doctest用例的集合。构造函数参数被用来初始化相同名称的属性。

DocTest 定义了以下属性。 它们由构造函数初始化，不应该被直接修改。

examples¶

一个 Example 对象的列表，它编码了应该由该测试运行的单个交互式 Python 用例。

globs¶

例子应该运行的命名空间（又称 globals ）。这是一个将名字映射到数值的字典。例子对名字空间的任何改变（比如绑定新的变量）将在测试运行后反映在 globs 中。

name¶

识别 DocTest 的字符串名称。 通常情况下，这是从测试中提取的对象或文件的名称。

filename¶

这个 DocTest 被提取的文件名；或者为``None``，如果文件名未知，或者 DocTest 没有从文件中提取。

lineno¶

filename 中的行号，这个 DocTest 开始的地方，或者行号不可用时为``None``。 这个行号相对于文件的开头来说是零的。

docstring¶

从测试中提取的字符串，或者如果字符串不可用，或者为 None ，如果测试没有从字符串中提取。

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

一个处理类，用于从一个给定的对象的 docstring 和其包含的对象的 docstring 中提取与之相关的 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 的 globals 是由 globs 和 extraglobs 组合而成的（ extraglobs 的绑定覆盖 globs 的绑定）。 为每个 DocTest 创建一个新的 globals 字典的浅层拷贝。如果没有指定 globs ，那么它默认为模块的 __dict__ ，如果指定了或者为 {} ，则除外。 如果没有指定 extraglobs ，那么它默认为 {} 。

DocTestParser 对象¶

class doctest.DocTestParser¶

一个处理类，用于从一个字符串中提取交互式的用例，并使用它们来创建一个 DocTest 对象。

DocTestParser 定义了以下方法：

get_doctest(string, globs, name, filename, lineno)¶

从给定的字符串中提取所有的测试用例，并将它们收集到一个 DocTest 对象中。

globs 、 name 、 filename 和 lineno 是新的 DocTest 对象的属性。 更多信息请参见 DocTest 的文档。

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

从给定的字符串中提取所有的测试用例，并以 Example 对象列表的形式返回。 行数以 0 为基础。 可选参数 name 是识别这个字符串的名称，只用于错误信息。

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

将给定的字符串分成用例和中间文本，并以 Example 和字符串交替的列表形式返回。 Example 的行号以 0 为基础。 可选参数 name 是识别这个字符串的名称，只用于错误信息。

DocTestRunner 对象¶

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

一个处理类，用于执行和验证 DocTest 中的交互式用例。

预期输出和实é™

输出之间的比较是由一个 OutputChecker 完成的。 这种比较可以用一些选项标志来定制；更多信息请看 选项标记 部分。 如果选项标志不够，那么也可以通过向构造函数传递 OutputChecker 的子类来定制比较。

测试运行器的显示输出可以通过两种方式控制。首å

ˆï¼Œä¸€ä¸ªè¾“出函数可以被传递给 TestRunner.run() ；这个函数将被调用，并显示出应该显示的字符串。 它的默认值是 sys.stdout.write 。 如果只捕获输出是不够的，那么也可以通过子类化 DocTestRunner ，并重写 report_start() , report_success() , report_unexpected_exception() , 和 report_failure() 方法来定制显示输出。

可选的å

³é”®å­—参数 checker 指定了 OutputChecker 对象（或替换），它应该被用来比较预期输出和 doctest 用例的实é™

输出。

可选的å

³é”®å­—参数 verbose 控制 DocTestRunner 的详细程度。 如果 verbose 是 True ，那么每个用例的信息都会被打印出来，当它正在运行时。 如果 verbose*是 ``False`` ，则只打印失败的信息。 如果 *verbose 没有指定，或è€

为 None ，如果当使用了命令行开å

³ -v ，则使用verbose输出。

可选的å

³é”®å­—参数 optionflags 可以用来控制测试运行器如何比较预期输出和实é™

输出，以及如何显示失败。更多信息，请参见章节 选项标记 。

DocTestParser 定义了以下方法：

report_start(out, test, example)¶

报告测试运行器即将处理给定的用例。提供这个方法是为了让 DocTestRunner 的子类能够定制他们的输出；它不应该被直接调用。

example 是即将被处理的用。 test 是 包含用例 的测试。 out 是传递给 DocTestRunner.run() 的输出函数。

report_success(out, test, example, got)¶

报告给定的例子运行成功。 提供这个方法是为了让 DocTestRunner 的子类能够定制他们的输出；它不应该被直接调用。

example 是即将被处理的用例。 got 是这个例子的实际输出。 test 是包含 example 的测试。 out 是传递给 DocTestRunner.run() 的输出函数。

report_failure(out, test, example, got)¶

报告给定的用例运行失败。 提供这个方法是为了让 DocTestRunner 的子类能够定制他们的输出；它不应该被直接调用。

example 是即将被处理的用例。 got 是这个例子的实际输出。 test 是包含 example 的测试。 out 是传递给 DocTestRunner.run() 的输出函数。

report_unexpected_exception(out, test, example, exc_info)¶

报告给定的用例触发了一个异常。 提供这个方法是为了让 DocTestRunner 的子类能够定制他们的输出；它不应该被直接调用。

example 是将要被处理的用例。 exc_info 是一个元组，包含关于异常的信息（如由 sys.exc_info() 返回）。 test 是包含 example 的测试。 out 是传递给 DocTestRunner.run() 的输出函数。

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

在 test （一个 DocTest 对象）中运行这些用例，并使用写入函数 out 显示结果。

这些用例都是在命名空间 test.globs 中运行的。 如果 clear_globs 为 True （默认），那么这个命名空间将在测试运行后被清除，以帮助进行垃圾回收。如果你想在测试完成后检查命名空间，那么使用 clear_globs=False 。

compileflags 给出了 Python 编译器在运行例子时应该使用的标志集。如果没有指定，那么它将默认为适用于 globs 的 future-import 标志集。

每个用例的输出都使用 DocTestRunner 的输出检查器进行检查，结果由 DocTestRunner.report_*() 方法进行格式化。

summarize(verbose=None)¶

打印这个 DocTestRunner 运行过的所有测试用例的摘要，并返回一个 named tupleTestResults(failed,attempted) 。

可选的 verbose 参数控制摘要的详细程度。 如果没有指定 verbose ，那么将使用 DocTestRunner 的 verbose 。

OutputChecker 对象¶

class doctest.OutputChecker¶

一个用于检查测试用例的实际输出是否与预期输出相匹配的类。 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 的选项标志集。