Python doctest模块 – 编写和测试代码文档

在Python中，文档测试（doctest）模块是一个非常有用的工具，可以用来编写和测试代码文档。它可以将文档中的代码示例提取出来，并执行它们来验证它们的正确性。使用doctest可以有助于保证代码和文档的一致性，并帮助开发者及时发现bug。

doctest基础知识

在Python中，可以将doctest测试用例写在函数、类、模块的doc字符串中。下面是一个示例：

def add_two_numbers(a, b):
    """
    This function adds two numbers together.

    >>> add_two_numbers(1, 1)
    2
    >>> add_two_numbers(2, 3)
    5
    """
    return a + b

在上面的例子中，我们定义了一个函数add_two_numbers，并在它的doc字符串中编写了测试用例。每个测试用例都以>>>开头，并在下一行中给出了预期输出。运行doctest，它将自动执行这些测试用例并报告测试结果。

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

doctest不仅可以检查函数的返回值是否正确，还可以检查函数中的异常是否正确抛出，以及在交互模式下输入是否正确。例如：

def divide_two_numbers(a, b):
    """
    This function divides two numbers.

    >>> divide_two_numbers(10, 2)
    5.0
    >>> divide_two_numbers(8, 0)
    Traceback (most recent call last):
        ...
    ZeroDivisionError: division by zero
    """
    return a / b

在上面的例子中，测试用例检查了在除数为0时，是否会正确抛出ZeroDivisionError异常。测试用例中的...表示可以在输入中输入任何值。测试用例中的>>>表示在Python解释器中输入代码。

在模块级别上运行测试用例

我们可以在模块级别上运行doctest来检查模块中的所有函数和类。如下所示：

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

这将执行模块中所有的doc字符串中的测试用例。可以在终端上使用以下命令行运行：

python -m doctest my_module.py

上面的命令行将运行my_module.py文件中的文档测试。在这种情况下，可以为testmod函数传递参数以指定要运行测试的模块或文档字符串。例如：

if __name__ == '__main__':
    import doctest
    doctest.testmod(m=my_module)

这将仅测试my_module.py文件中的文档测试。

关闭doctest

有时候我们可能想要关闭doctest测试。我们可以在doc字符串中添加doctest: +SKIP标记，这样doctest将跳过这个测试用例。例如：

def add_two_numbers(a, b):
    """
    This function adds two numbers together.

    >>> add_two_numbers(1, 1)
    2
    >>> add_two_numbers(2, 3)  # doctest: +SKIP
    6
    """
    return a + b

上面的例子中，在第二个测试用例后面添加了doctest: +SKIP标记，这意味着这个测试用例将被跳过。

结论

在Python中，使用doctest模块可以非常方便地编写和测试Python代码的文档字符串。文档测试可以确保代码和文档的一致性，并可以帮助您及时发现bug。不过，我们需要注意doctest不适用于所有情况，并且文档测试不是一个完整的单元测试框架。因此，在使用doctest时，需要选择合适的测试用例，并使用其他测试工具进行更全面的测试。