doctest API围绕以下两个容器类，这些容器类用于存储来自docstrings的交互式示例-

• 示例-单个Python语句及其预期输出。

• DocTest-示例的集合，通常从单个文档字符串或文本文件中提取。

定义了以下其他处理类以查找，解析和运行以及检查doctest示例-

• DocTestFinder-查找给定模块中的所有文档字符串，并使用DocTestParser从每个包含交互式示例的文档字符串创建DocTest。

• DocTestParser-从字符串(例如对象的文档字符串)创建doctest对象。

• DocTestRunner-在doctest中执行示例，并使用OutputChecker验证其输出。

• OutputChecker-将doctest示例的实际输出与预期输出进行比较，并确定它们是否匹配。

DocTestFinder类别

它是一个处理类，用于从其文档字符串及其包含的对象的文档字符串中提取与给定对象相关的doctest。当前可以从以下对象类型中提取doctest-模块，函数，类，方法，静态方法，类方法和属性。

此类定义find()方法。它返回由对象的文档字符串或其任何包含的对象的文档字符串定义的DocTest的列表。

DocTestParser类

它是一个处理类，用于从字符串提取交互式示例，并使用它们创建DocTest对象。此类定义以下方法-

• get_doctest() -从给定的字符串提取所有doctest示例，并将其收集到DocTest对象中。

• get_examples(字符串[，name]) -从给定的字符串提取所有doctest示例，并将其作为Example对象列表返回。行号从0开始。可选参数名称是标识此字符串的名称，并且仅用于错误消息。

• parse(字符串[，name]) -将给定的字符串划分为示例和中间文本，然后将它们作为示例和字符串的交替列表返回。示例的行号从0开始。可选参数名称是标识此字符串的名称，并且仅用于错误消息。

DocTestRunner类

这是一个处理类，用于执行和验证DocTest中的交互式示例。其中定义了以下方法-

report_start()

报告测试运行程序将要处理给定的示例。提供此方法是为了允许DocTestRunner的子类自定义其输出。不应直接调用

report_success()

报告给定的示例已成功运行。提供此方法是为了允许DocTestRunner的子类自定义其输出。不应直接调用它。

report_failure()

报告给定的示例失败。提供此方法是为了允许DocTestRunner的子类自定义其输出。不应直接调用它。

report_unexpected_exception()

报告给定的示例引发了意外的异常。提供此方法是为了允许DocTestRunner的子类自定义其输出。不应直接调用它。

运行(测试)

运行测试中的示例(一个DocTest对象)，并使用writer函数out显示结果。

摘要([详细])

打印此DocTestRunner已运行的所有测试用例的摘要，并返回一个命名的元组TestResults(失败，已尝试)。可选的详细参数控制摘要的详细程度。如果未指定详细程度，则使用DocTestRunner的详细程度。

OutputChecker类

此类用于检查doctest示例的实际输出是否与预期输出匹配。

在此类中定义了以下方法-

check_output()

如果示例的实际输出( got )与预期的输出( want )相匹配，则返回True 。如果这些字符串相同，则始终被视为匹配。但是根据测试运行程序使用的选项标记，也可以使用几种非完全匹配类型。有关选项标志的更多信息，请参见选项标志和指令一节。

output_difference()

返回一个字符串，该字符串描述给定示例( example )的预期输出与实际输出( got )之间的差异。

DocTest与Unittest集成

doctest模块提供了两个功能，可用于从包含doctests的模块和文本文件中创建单元测试套件。要与unittest测试发现集成，请在测试模块中包含load_tests()函数-

import unittest
import doctest
import doctestexample

def load_tests(loader, tests, ignore):
   tests.addTests(doctest.DocTestSuite(doctestexample))
   return tests

将形成来自unittest和doctest的组合TestSuite测试，现在可以通过unittest模块的main()方法或run()方法执行它。

以下是创建带有doctests的文本文件和模块中的unittest.TestSuite实例的两个主要功能-

doctest.DocFileSuite()

它用于将doctest测试从一个或多个文本文件转换为unittest.TestSuite 。返回的unittest.TestSuite将由unittest框架运行，并在每个文件中运行交互式示例。如果文件中的任何示例失败，则合成的单元测试将失败，并且会引发failureException异常，该异常显示包含测试的文件的名称和(有时是近似的)行号。

doctest.DocTestSuite()

它用于将模块的doctest测试转换为unittest.TestSuite 。

返回的unittest.TestSuite将由unittest框架运行，并运行模块中的每个doctest。如果任何doctest测试失败，则综合单元测试失败，并引发failException异常，显示包含测试的文件名和(有时是近似的)行号

在幕后，DocTestSuite()从doctest.DocTestCase实例中创建一个unittest.TestSuite ，而DocTestCase是unittest.TestCase的子类。

同样，DocFileSuite()从doctest.DocFileCase实例中创建一个unittest.TestSuite，而DocFileCase是DocTestCase的子类。

因此，创建unittest.TestSuite的两种方法都可以运行DocTestCase的实例。自己运行doctest函数时，可以通过将选项标志传递给doctest函数来直接控制正在使用的doctest选项。

但是，如果您正在编写一个单元测试框架，则单元测试最终将控制测试的运行时间和方式。框架作者通常希望控制doctest报告选项(例如，由命令行选项指定)，但是无法将选项通过unittest传递给doctest测试运行者。