doctest Unittest API

随着您的文档测试模块集合的增长，您需要一种系统地运行所有文档测试的方法。在Python 2.4之前，doctest有一个几乎没有文档记录的Tester类，它提供了一个基本方法来组合多个模块的doctests。Tester是虚弱的，实际上最严重的Python测试框架建立在unittest模块上，它提供了许多灵活的方法来结合多个来源的测试。所以，在Python 2.4，doctest的Tester类已被弃用，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

有两个主要的功能可以用unittest.TestSuite文本文件和模块创建实例：

doctest.DocFileSuite(*paths, [module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])

将doctest测试从一个或多个文本文件转换为unittest.TestSuite。

返回的unittest.TestSuite内容将由unittest框架运行并在每个文件中运行交互式示例。如果任何文件中的示例失败，则合成的单元测试将失败，并failureException引发异常，显示包含测试的文件的名称和一个（有时是近似的）行号。

将一个或多个路径（字符串）传递给要检查的文本文件。

选项可以作为关键字参数提供：

可选参数module_relative指定应如何解释路径中的文件名：

• 如果module_relative是True（缺省值），则路径中的每个文件名指定与操作系统无关的模块相对路径。默认情况下，这个路径是相对于调用模块的目录; 但是如果指定了package参数，那么它与该包相关。为确保操作系统无关性，每个文件名应使用/字符来分隔路径段，并且可能不是绝对路径（即可能不以其开头/）。

• 如果module_relative是False，则路径中的每个文件名都指定一个OS特定的路径。路径可以是绝对的或相对的; 相对路径相对于当前工作目录被解析。

可选参数包是Python包或Python包的名称，其目录应该用作路径中与模块相关的文件名的基本目录。如果未指定包，则调用模块的目录将用作模块相关文件名的基本目录。如果module_relative是指定包，那是False错误的。

可选参数setUp指定测试套件的设置函数。这在每个文件中运行测试之前被调用。该的setUp函数将被传递一个DocTest对象。setUp函数可以在测试的globs属性通过时访问测试全局变量。

可选参数tearDown指定测试套件的拆卸函数。这是在每个文件中运行测试后调用的。在拆卸会被传递给一个DocTest对象。setUp函数可以在测试的globs属性通过时访问测试全局变量。

可选参数globs是包含测试的初始全局变量的字典。每个测试都会创建一本新字典。默认情况下，globs是一个新的空字典。

可选参数optionflags指定测试的默认doctest选项，由各个选项标记组合或创建。请参见选项标志部分。请参阅set_unittest_reportflags()下面的功能以更好地设置报告选项。

可选参数解析器指定DocTestParser应该用于从文件中提取测试的一个（或子类）。它默认为一个普通的解析器（即，DocTestParser()）。

可选的参数编码指定应该用于将文件转换为unicode的编码。

2.4版本中的新功能。

在版本2.5中进行了更改：将全局__file__添加到提供给使用文本文件加载的文档测试的全局文件中DocFileSuite()。

在版本2.5中更改：添加了参数编码。

注意

不像testmod()和DocTestFinder，ValueError如果模块不包含文档字符串，该函数会引发一个问题。您可以通过传递一个DocTestFinder实例作为test_finder参数，并将其exclude_empty关键字参数设置为False：

>>> finder = doctest.DocTestFinder(exclude_empty=False)
>>> suite = doctest.DocTestSuite(test_finder=finder)

doctest.DocTestSuite([module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])

将模块的doctest测试转换为一个模块unittest.TestSuite。

返回的unittest.TestSuite是由unittest框架运行并在模块中运行每个doctest。如果有任何文档测试失败，则合成的单元测试失败，并failureException引发异常，显示包含测试的文件的名称和一个（有时是近似的）行号。

可选参数模块提供要测试的模块。它可以是一个模块对象或一个（可能点缀的）模块名称。如果未指定，则使用调用此函数的模块。

可选参数globs是包含测试的初始全局变量的字典。每个测试都会创建一本新字典。默认情况下，globs是一个新的空字典。

可选参数extraglobs指定一组额外的全局变量，这是合并成的水珠。默认情况下，不使用额外的全局变量。

可选参数test_finder是DocTestFinder用于从模块中提取doctests 的对象（或插入替换）。

可选参数setUp，tearDown和optionflags与DocFileSuite()上面的函数相同。

2.3版本的新功能。

在版本2.4中更改：添加了参数globs，extraglobs，test_finder，setUp，tearDown和optionflags ; 这个功能现在使用和。一样的搜索技术testmod()。

在幕后，DocTestSuite()创建unittest.TestSuite出的doctest.DocTestCase实例，DocTestCase是的子类unittest.TestCase。DocTestCase这里没有记录（这是一个内部细节），但是研究它的代码可以回答关于unittest集成确切细节的问题。

同样，DocFileSuite()创建unittest.TestSuite出的doctest.DocFileCase实例，DocFileCase是的子类DocTestCase。

因此创建unittest.TestSuite运行实例的两种方式DocTestCase。这对于一个微妙的原因很重要：当你doctest自己运行函数时，可以doctest通过将选项标志传递给doctest函数来直接控制正在使用的选项。但是，如果你正在编写一个unittest框架，unittest最终控制何时以及如何运行测试。框架作者通常希望控制doctest报表选项（可能例如由命令行选项指定），但是没有办法将选项传递unittest给doctest测试运行者。

出于这个原因，doctest还支持通过此功能支持doctest特定于unittest支持的报告标志的概念：

doctest.set_unittest_reportflags(flags)

设置doctest要使用的报告标志。

参数标志或一起选项标志。请参见选项标志部分。只能使用“报告标志”。

这是一个模块全局设置，并影响模块运行的所有将来的doctests unittest：在DocTestCase实例构建时查看为测试用例指定的选项标记DocTestCase的runTest()方法。如果没有指定报告的标志（这是典型的和预期的情况下），doctest的unittest报告标志是按位或运算进入选项标志，因此增强选项标志传递给创建运行文档测试DocTestRunner实例。如果时指定的任何报告的标志例如构建DocTestCase，doctest的unittest报告标志被忽略。

在函数被调用之前生效的报告标志的值由函数返回unittest。

New in version 2.4.