单元测试框架 - Doctest API

上一页
下一页

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

  • 示例 - 单个 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(string[, name]) - 从给定字符串中提取所有 doctest 示例，并将它们作为Example对象的列表返回。行号为基于 0 的。可选参数 name 是标识此字符串的名称，仅用于错误消息。

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

DocTestRunner 类

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

report_start()

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

report_success()

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

report_failure()

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

report_unexpected_exception()

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

run(test)

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

summarize([verbose])

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

OutputChecker 类

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

此类中定义了以下方法：

check_output()

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

output_difference()

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

DocTest 与 Unittest 的集成

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() 方法执行。

以下是用于从包含 doctest 的文本文件和模块创建unittest.TestSuite实例的两个主要函数：

doctest.DocFileSuite()

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

doctest.DocTestSuite()

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

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

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

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

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

但是，如果您正在编写 unittest 框架，unittest 最终会控制测试何时以及如何运行。框架作者通常希望控制 doctest 报告选项（例如，由命令行选项指定），但是没有办法通过 unittest 将选项传递给 doctest 测试运行器。

打印页面
上一页
下一页
广告