如何在 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


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

你可能感兴趣的:(Python,python,网络,服务器)