Python doctest模块详解（新手也能轻松掌握的自动化测试利器）

什么是 doctest？

doctest 是 Python 标准库中的一个模块，它的核心思想是：将交互式解释器中的输入和输出直接写入文档字符串中，然后让程序自动运行这些示例并检查输出是否匹配。

这种方式不仅便于测试，还能确保你的文档始终与代码保持同步——因为如果代码变了但文档没更新，测试就会失败！

第一个 doctest 示例

让我们从一个简单的函数开始：

def add(a, b):    """    返回两个数的和。    >>> add(2, 3)    5    >>> add(-1, 1)    0    """    return a + bif __name__ == "__main__":    import doctest    doctest.testmod(verbose=True)

在这个例子中，我们在函数的 docstring 中写了两个测试用例，格式模仿了 Python 交互式解释器（以 >>> 开头）。当我们运行这个脚本时，doctest.testmod() 会自动查找所有 docstring 中的测试用例并执行它们。

如何运行 doctest？

有几种方式可以运行 doctest 测试：

1. 在脚本末尾调用 doctest.testmod()（如上例所示）
2. 使用命令行运行：
   python -m doctest your_script.py
3. 启用详细输出（查看每个测试结果）：
   python -m doctest -v your_script.py

处理异常和复杂输出

有时函数会抛出异常，或者输出包含不可预测的内容（如时间戳）。doctest 提供了灵活的选项来处理这些情况。

例如，测试一个除零错误：

def divide(a, b):    """    返回 a 除以 b 的结果。    >>> divide(10, 2)    5.0    >>> divide(1, 0)    Traceback (most recent call last):        ...    ZeroDivisionError: division by zero    """    return a / b

注意这里使用了 ... 来省略中间的堆栈信息，只要异常类型和消息匹配即可通过测试。

高级技巧：忽略空白和浮点精度

默认情况下，doctest 对输出的空格和换行非常敏感。你可以通过设置选项来放宽要求：

def calculate_area(r):    """    计算圆的面积。    >>> calculate_area(2)  # doctest: +ELLIPSIS    12.566...    """    import math    return math.pi * r ** 2

上面使用了 # doctest: +ELLIPSIS 指令，允许用 ... 匹配任意字符，非常适合处理浮点数。

为什么使用 doctest？

• ✅ 简单直观：无需额外学习复杂的测试框架语法
• ✅ 文档即测试：确保示例代码始终有效
• ✅ 内置支持：Python 标准库自带，无需安装第三方包
• ✅ 适合教学和小型项目：快速验证函数行为

总结

通过这篇 Python doctest模块 教程，你应该已经掌握了如何在自己的项目中使用 doctest 进行基本的 Python 单元测试 和 Python 自动化测试。虽然对于大型项目你可能需要更强大的测试框架（如 unittest 或 pytest），但 doctest 在保持文档准确性和快速验证逻辑方面依然无可替代。

现在就打开你的 Python 编辑器，给你的函数加上几个 >>> 测试吧！你会发现，写测试原来可以这么简单又有趣。