Python 有个隐藏的“测试神器”，代码写在文档里就能跑

揭开 Python 标准库中的“遗珠”：doctest框架

在 Python 的开发历程中，测试无疑是保障代码质量的基石。作为一名 Python 开发者，你可能早已对**unittest、pytest等成熟的测试框架驾轻就熟，甚至已经构建了复杂的持续集成（CI）流程来自动化你的测试工作。不过，你知道吗？自Python 2.1**版本——一个相当古老的版本——开始，Python 就默默地内置了一个原生的测试框架，它被深藏在标准库中，但却鲜有开发者能充分利用它的价值，甚至不知道它的存在。

这个“隐藏的宝石”就是**doctest**。

doctest是 Python 标准库中最被低估的工具之一。它的核心思想是颠覆传统测试模式：你不需要为你的代码单独创建一个庞大的测试套件文件，而是可以将测试用例直接嵌入到你的函数的docstrings（文档字符串）中。

这意味着，你的文档和测试实现了“同居”。它们生活在同一个地方，消除了代码和文档之间的内容重复，也让你没有借口不对代码进行测试。

本文将深入剖析doctest的工作原理、它真正的优势所在、它适用的场景（以及它的局限性），并教你如何立即将它融入你的开发流程，从而写出更清晰、更健壮的 Python 代码。

doctest的本质：文档即代码，示例即测试

要理解doctest，我们只需把握一个简单的核心理念：

你在docstrings中编写的示例，就像你在 Python 交互式解释器（REPL）中输入的那样。

随后，doctest框架会执行这些文档中的示例代码，并检查它们的输出是否与你期望的输出完全匹配。如果匹配，测试通过；如果不匹配，则失败。

最直观的入门示例

让我们通过一个最简单的加法函数来直观感受doctest的工作方式：

def add(a, b):
    """
    Returns the sum of a and b.

    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    """
    return a + b

注意看，在函数的docstring中，我们用>>>开头模拟了 REPL 的输入提示符。紧接着的下一行，就是我们期望的输出结果。

如何运行doctest

运行这些内置测试超级简单，你甚至不需要编写任何额外的启动代码。只需要通过命令行调用 Python 的doctest模块：

python -m doctest -v your_file.py

如果你运行上述命令，输出结果将清晰地展示测试过程：

Trying:
    add(2, 3)
Expecting:
    5
ok
Trying:
    add(-1, 1)
Expecting:
    0
ok

整个过程清晰明了。你的docstring既是面向用户的文档，也是验证代码逻辑的测试。

为什么说doctest是一个隐藏的“超能力”

既然我们已经有了像pytest和unittest这样功能强劲的框架，为什么还要关注doctest呢？答案在于它独特的优势和定位。

1. 文档与测试的“一站式”解决方案

这是doctest最强劲的特性：

你的docstrings目前包含了具体的、可执行的代码示例。
告别那些随着代码迭代而腐烂、过时的“示例代码”。
由于这些示例代码位于docstring中，它们会被执行并通过测试，否则测试将失败，确保了文档的实时有效性。

2. 零配置、零依赖的即插即用

在现代开发中，安装和配置测试运行器及各种依赖库往往是耗时的第一步。但doctest完全消除了这个烦恼：

无需安装任何测试运行器。
无需任何额外的库。
它内置于标准库中，只要你的 Python 环境存在，doctest就永远可用。

3. 轻量级函数的最佳搭档

并非所有函数都需要一个功能完整的测试套件来验证。

对于那些琐碎的、简单的辅助函数（Helper Functions），使用doctest可以保持测试的精益和轻量。它避免了为简单的逻辑编写繁琐的测试文件和样板代码。

4. 推动更好的文档编写习惯

开发者一般会忽视甚至逃避编写文档。

有了doctest，编写文档就等于同时在编写测试，实现“一举两得”。它鼓励开发者在设计函数时，同步思考如何向使用者展示其功能，从而自不过然地提高了文档的质量和覆盖率。

doctest大放异彩的四大应用场景

虽然doctest无意取代大型测试框架，但在特定的场景下，它却异常高效和实用。

1.教育和教学代码

如果你正在教授 Python 或分享代码片段，doctest是保证你的所有示例都能正常工作的最佳方式。学习者可以直接从文档中获取可运行、已验证的示例，大大提升学习体验。

2.纯函数和工具函数

对于那些短小精悍的纯函数（输入确定，输出也确定，没有副作用），doctest是理想的选择。例如，一个计算阶乘的函数：

def factorial(n):
    """
    Compute n factorial.

    >>> factorial(0)
    1
    >>> factorial(5)
    120
    """
    return 1 if n == 0 else n * factorial(n-1)

3.原型设计与快速实验

当你需要快速验证一段逻辑或进行实验性编程时，你可以直接将测试逻辑写在docstring中，而无需先停下来编写一个完整的测试套件。这有助于你快速迭代和验证想法。

4.文档驱动开发 (DDD) 或文学编程

如果你喜爱文学编程（Literate Programming），或者推崇文档驱动的开发模式，doctest会是你的得力助手。它将代码的解释、示例和验证紧密地整合在一起，让文档成为代码设计的中心。

认识doctest的局限性：它不是万能药

任何工具都有其适用范围。虽然doctest超级出色，但它也存在一些固有的缺点，使其无法胜任所有测试任务。我们需要将其视为对其他测试框架的补充，而非替代品。

1.对空白符的严格敏感性

doctest在匹配输出文本时是字面量匹配（literally matches texts）的。

这意味着，格式（包括空格、换行符）至关重大。即使是输出中多了一个空格，测试也会失败。这种严格性在某些情况下可能会让人感到沮丧。

2.复杂输出的处理难题

对于那些输出结果不确定或难以预测的场景，doctest的表现会大打折扣：

包含内存地址的对象：例如，对象或列表的repr()可能包含内存地址，每次运行都会变化，导致匹配失败。
浮点数精度差异：微小的浮点数计算差异也会导致文本匹配失败。

3.大型测试套件的伸缩性不足

当项目代码规模庞大，需要大规模测试套件时，pytest或unittest等框架因其结构化和隔离性，能更好地处理可伸缩性问题。将数千个测试用例散布在各个docstring中，管理和概览将变得困难。

4.缺乏高级测试特性

doctest是一个极简框架，它不提供现代测试框架中常见的高级功能：

Fixtures（测试夹具）：用于设置和清理测试环境。
Mocking（模拟）：用于隔离外部依赖或复杂组件。
Parameterized Tests（参数化测试）：用于用同一套逻辑测试多组输入。

因此，对于那些需要复杂环境设置、外部服务隔离或大量输入组合的测试，开发者仍应首选pytest或unittest。

进阶技巧：解锁doctest的更灵活用法

如果你决定认真对待doctest，了解一些高级用法将使其在实际应用中更加灵活。

1. 在代码中运行doctest

除了使用命令行，你也可以选择在 Python 代码运行时以编程方式执行doctest：

if __name__ == "__main__":
    import doctest
    doctest.testmod()

将这段代码添加到你的脚本末尾，运行脚本时就会自动执行其中的doctest。

2. 忽略输出中的细微差异（ELLIPSIS）

面对那些输出中有部分内容会发生变化，但核心逻辑不变的情况，doctest提供了ELLIPSIS（省略号）选项来增加灵活性：

def greet(name):
    """
    Say hello.

    >>> greet("Alice")
    'Hello, Alice...'
    """
    return f"Hello, {name}..."

if __name__ == "__main__":
    import doctest
    # 使用 optionflags 启用 ELLIPSIS
    doctest.testmod(optionflags=doctest.ELLIPSIS)

在测试示例的期望输出中使用…，可以匹配输出字符串中可变的任意部分。

3. 测试外部文档文件

doctest的强劲之处在于，它不仅限于测试.py文件中的docstrings。你也可以用它来测试独立的文档文件，例如 Markdown 文件：

python -m doctest -v README.md

这条命令可以确保你的README.md或其他文档中提供的所有代码示例都是正确可执行的。这对于维护开源项目或提供高质量教程文档至关重大。

doctest与pytest：并非“二选一”的抉择

一个很自然的问题是：我已经在使用pytest了，还需要doctest吗？

答案是肯定的，它们可以完美地共存，并实现互补。

职责划分的黄金法则

使用doctest：用于文档示例、教学教程和小型辅助函数的快速、轻量级验证。它专注于“这个函数是如何使用的？”的场景。
使用pytest：用于大规模的、生产级别的、结构化的测试，包括集成测试、需要 Mocking 和 Fixtures 的复杂场景。它专注于“这个模块在所有边界条件下是否健壮？”的场景。

实际上，pytest本身就原生支持运行doctest。你只需在运行pytest时添加一个命令行参数：

pytest --doctest-modules

这样，pytest就会在你运行常规测试的同时，自动发现并执行所有模块中的doctest。

核心理念是：你不需要做选择题。在方便时使用doctest，在需要强劲功能时使用pytest。

真实案例：doctest如何捕获一个微小但关键的 Bug

通过一个真实的开发故事，我们更能体会doctest在日常工作中的价值。

在我的一个博客项目中，有一个简单的slugify函数，用于将文本转换为 URL 友善的短链接。它的docstring中包含了如下示例：

def slugify(text):
    """
    Convert text into a URL slug.

    >>> slugify("Hello World")
    'hello-world'
    """
    return text.lower().replace(" ", "-")

这段代码看似简单，但当我尝试运行doctest时，它失败了。为什么？

问题出在了细节上：当输入是”Hello World”（中间有两个空格）时，我的简单实现会打印出”hello–world”。而我的测试期望结果是'hello-world'，两者不匹配，测试失败。

这个微小的失败促使我思考并改善了功能，最终我使用了正则表达式（regex）来处理任意数量的空格，确保只生成一个短划线。

如果没有doctest，我可能根本不会意识到这个边缘条件（edge condition），直到它在生产环境中导致了难以预料的问题。这再次证明了doctest的价值：它促使你像用户一样思考，并确保你文档中的示例是正确的。