最强Python测试框架——doctest，让你的代码文档变得既有趣又高效

Python的测试框架有很多种，其中 doctest 被认为是最简单、最直接的一种。它不仅能帮助你进行代码的单元测试，还能让你的代码文档更加生动有趣！通过在文档字符串中嵌入简单的测试例子，doctest 允许你验证文档中的代码是否与实际输出一致。本文将详细介绍 doctest 的用法，展示如何通过几个简单的例子来让你的代码既容易理解，又能自动化测试。

什么是 `doctest`？

doctest 是Python标准库中的一个模块，允许你在文档字符串中嵌入示例代码，并自动检查代码的输出是否与预期匹配。它主要用于小型的、简单的单元测试，帮助你确保代码与文档中描述的一致。

通常，doctest 被用来对函数的行为进行快速的单元测试，同时提升文档的可读性。

如何使用 `doctest`？

doctest 的使用方式非常简单，核心思想是将代码片段和期望的输出写入函数的文档字符串中。当你运行 doctest 时，它会执行这些代码并将实际输出与期望输出进行比对。如果两者一致，测试通过；如果不一致，测试失败。

基本用法

我们先来看一个最基本的例子，展示如何通过 doctest 来测试一个简单的加法函数。

import doctest

def add(a, b):
    """
    返回两个数的和。

    示例:
    >>> add(1, 2)
    3
    >>> add(5, 7)
    12
    >>> add(-1, 1)
    0
    """
    return a + b

# 运行doctest来验证文档中的代码
doctest.testmod()

解释

我们定义了一个简单的加法函数 add，并在它的文档字符串中嵌入了三个例子。每个例子都包含了输入值和期望输出。
doctest.testmod()

会自动扫描文档字符串中的测试示例并运行它们。如果实际输出与期望输出不匹配，doctest 会报告错误。

运行结果

当我们运行这个脚本时，doctest 会检测文档中的例子，自动执行代码，并确保输出结果与注释中的期望一致。若输出匹配，则测试通过；如果不匹配，会在控制台输出相应的错误信息。

进阶用法

虽然 doctest 很简单，但它也支持更复杂的功能，比如忽略浮动误差、匹配输出的部分内容等。

忽略浮动误差

在一些涉及浮点数运算的测试中，我们通常会遇到精度问题。此时可以使用 doctest 的 + 标记来表示输出值应该忽略浮动误差。

import doctest

def divide(a, b):
    """
    返回a除以b的结果。

    示例:
    >>> divide(10, 2)
    5.0
    >>> divide(7, 3)
    2.3333333333333335
    """
    return a / b

doctest.testmod()

这个例子中的浮点数结果可能因计算机的浮动精度而不完全相同。doctest 允许我们忽略这些微小差异，默认情况下，它会尝试输出与注释匹配。

只匹配输出的一部分

如果你只关心输出的某一部分（比如你不关心某个动态生成的 ID），你可以使用 doctest 的 ... 来表示输出的一部分内容。

import doctest

def create_object(name):
    """
    创建一个对象，并返回它的字符串表示。

    示例:
    >>> obj = create_object('python')
    >>> obj
    <Object: python, ID: ...>  # ID部分是动态生成的，可以忽略
    """
    return f"<Object: {name}, ID: {id(name)}>"

doctest.testmod()

选择性地运行 `doctest`

如果你只想运行文档字符串中的某些测试，可以通过命令行参数或直接调用某个特定模块的方式来控制。

doctest.testmod(name="module_name")

`doctest` 与其他测试框架的对比

简单易用

：doctest 的语法与文档自然融合，非常适合用来验证文档中的代码片段。
适合小范围测试

：相比于像 unittest 和 pytest 这样的框架，doctest 更适合进行简单的小型测试，特别是当你不希望额外编写繁琐的测试代码时。
不适用于复杂场景

：doctest 更适合用来测试简单的函数和操作，对于复杂的测试场景，它可能不够灵活或全面。