如何在 Python 的文档中写测试 - doctest 指南

在Python中，doctest是一个内置的模块，用于测试和文档化代码。它允许你在文档字符串中嵌入测试示例，并自动运行这些示例来验证代码的正确性。doctest通过在文档字符串中使用特殊的注释语法来编写测试用例，并执行这些测试来确保代码的正确性。

doctest 格式

其实 doctest 这个命名已经透露出了它的一些信息了。

我们需要将 doctest 写在文档字符串中，也就是 """ 中间，比如下面这个：

"""
>>> add(2, 3)
5
"""

这里表示一个测试用例，表示调用了 add(2, 3) 之后，会返回结果 5。

注意：需要严格按照上面的格式来写 doctest，也就是 >>> 开头接测试代码，然后接下来一行写测试结果。

下面是更加详细的讲解。

三步实现 Doctest 测试

1. 在文档中加入测试用例

def add(a, b):
    """
    计算两数之和

    :param a: int
    :param b: int
    :return: int

    >>> add(2, 3)
    5

    >>> add(0, 0)
    0
    """
    return a + b

在这个例子，我们添加了两个测试用例：

• add(2, 3) 返回结果 5
• add(0, 0) 返回结果 0

2. 引入 doctest 模块并进行测试

在上面的例子基础上，我们 import doctest 并且调用它的 testmod 方法就可以实现文档测试了：

# 导入 doctest 模块
import doctest

def add(a, b):
    """
    计算两数之和

    :param a: int
    :param b: int
    :return: int

    >>> add(2, 3)
    5

    >>> add(0, 0)
    0
    """
    return a + b

# 进行测试
if __name__ == '__main__':
    doctest.testmod()

3. 运行文件

我们运行这个文件就可以进行测试了。如果我们的测试用例没有问题，则我们的程序会正常退出。如果测试用例不通过，则会给出对应的报错信息：

假如我们修改一下上面的测试用例：

>>> add(0, 1)
0

再次执行，则会报错了：

Failure
<Click to see difference>

**********************************************************************
File "/Users/ruby/WeChatProjects/github_api/temp/d.py", line 14, in add
Failed example:
    add(0, 1)
Expected:
    0
Got:
    1

因为 0 + 0 = 0 而不是 1。

总结

python 中的 doctest 允许我们在文档中写一些测试用例，这对于一些简单的函数测试来说就够用了，可以给我们带来很多的便利。这种结构允许你将文档和测试紧密集成在一起，使得文档不仅仅是描述代码的地方，还是代码正确性的验证工具。