掌握Python文档测试利器（手把手教你使用doctest库进行自动化测试）

什么是 doctest？

doctest 是Python内置的一个模块，它的核心思想是：文档即测试。你可以在函数的 docstring 中写入交互式 Python 会话（就像你在 Python REPL 中输入的一样），doctest 会自动提取这些示例并验证它们的输出是否与预期一致。

为什么使用 doctest？

• 保持文档与代码同步：测试失败说明文档过时了。
• 简单易学：无需额外学习复杂语法，直接使用 Python 交互式命令。
• 适合教学和示例：清晰展示函数如何使用。
• 作为轻量级 Python单元测试 补充。

第一个 doctest 示例

让我们编写一个简单的阶乘函数，并在 docstring 中加入测试：

def factorial(n):    """    计算 n 的阶乘。    >>> factorial(0)    1    >>> factorial(1)    1    >>> factorial(5)    120    >>> factorial(-1)  # 负数应抛出异常    Traceback (most recent call last):        ...    ValueError: n 必须是非负整数    """    if n < 0:        raise ValueError("n 必须是非负整数")    if n == 0 or n == 1:        return 1    result = 1    for i in range(2, n + 1):        result *= i    return resultif __name__ == "__main__":    import doctest    doctest.testmod(verbose=True)

保存为 factorial.py 并运行：

$ python factorial.py

如果所有测试通过，你会看到类似这样的输出：

Trying:    factorial(0)Expecting:    1ok...1 items had no tests:    __main__1 items passed all tests:   4 tests in __main__.factorial4 tests in 2 items.4 passed and 0 failed.Test passed.

doctest 的基本规则

1. 每个测试用例以 >>> 开头（代表 Python REPL 提示符）。
2. 紧接着是你要执行的代码。
3. 下一行是期望的输出（必须完全匹配，包括空格和换行）。
4. 对于异常，可以使用 Traceback ... 并用 ... 省略中间细节。

常见选项与技巧

有时输出包含动态内容（如时间戳、内存地址），可使用 ELLIPSIS 选项：

def greet(name):    """    返回问候语。    >>> greet('Alice')  # doctest: +ELLIPSIS    'Hello, Alice! Time: ...'    """    import datetime    return f"Hello, {name}! Time: {datetime.datetime.now()}"

总结

Python doctest 是一个简单却高效的工具，特别适合用于编写示例驱动的文档和轻量级测试。通过将测试嵌入文档，你不仅能保证代码正确性，还能让文档始终保持最新。对于初学者来说，它是理解 Python单元测试 概念的绝佳入口；对于老手，则是快速验证函数行为的利器。

现在就尝试在你的下一个项目中加入 doctest 吧！你会发现，文档测试 让你的代码更可靠、更易维护。

希望这篇 doctest教程 能帮助你轻松上手这个实用的 Python 测试工具！