单元测试框架 - Doctest API

doctest API 围绕以下两个容器类，用于存储文档字符串中的交互式示例 -

  • 示例- 单个 Python 语句与其预期输出配对。

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

定义以下附加处理类来查找、解析、运行和检查 doctest 示例 -

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

  • DocTestParser - 从字符串（例如对象的文档字符串）创建文档测试对象。

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

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

DocTestFinder 类

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

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

DocTestParser 类

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

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

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

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

DocTestRunner 类

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

报告开始（）

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

报告_成功()

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

报告失败（）

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

报告意外异常（）

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

运行（测试）

运行test中的示例（DocTest 对象），并使用 writer 函数out显示结果。

总结（[详细]）

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

输出检查器类

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

此类中定义了以下方法 -

检查输出（）

如果示例的实际输出 ( got ) 与预期输出 ( want )匹配，则返回True 。如果这些字符串相同，则始终认为它们匹配；但根据测试运行程序使用的选项标志，也可能有几种非精确匹配类型。有关选项标志的更多信息，请参阅选项标志和指令部分。

输出差异（）

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

DocTest 与单元测试集成

doctest 模块提供了两个函数，可用于从包含 doctest 的模块和文本文件创建 unittest 测试套件。要与 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。如果任何文档测试失败，则合成的单元测试失败，并引发failureException异常，显示包含测试的文件的名称和（有时是近似的）行号

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

类似地，DocFileSuite() 从 doctest.DocFileCase 实例中创建一个 unittest.TestSuite，并且 DocFileCase 是 DocTestCase 的子类。

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

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