轻松入门：Python -m doctest 使用指南

Python -m doctest 教程

简介

Python 的 doctest 模块是一种测试工具，可以自动提取代码中的文档字符串中的示例，并运行这些示例作为测试。这个模块让编写和维护测试案例变得简单，同时也可以作为文档的一部分使用。在本教程中，我们将深入了解 python -m doctest 命令以及如何使用它。

摘要

本教程涵盖了以下内容：

使用 python -m doctest 命令运行 doctest
编写 doctest 用例
在函数文档字符串中编写测试案例
在模块文档字符串中编写测试案例
运行包含 doctest 的模块或脚本
忽略输出结果中的不相干部分
使用 doctest.ELLIPSIS 忽略部分输出
使用 doctest.NORMALIZE_WHITESPACE 校正空白字符
在测试中引用其他函数或类
通过 doctest 模块中的 API 运行测试

以下是每个部分的详细步骤和示例代码。

安装和准备

在开始之前，请确保已经正确安装了 Python。doctest 模块是 Python 标准库的一部分，所以不需要额外的安装。

1. 使用 `python -m doctest` 命令运行 doctest

通过 python -m doctest 命令，我们可以运行包含 doctest 的模块或脚本。

def add(a, b):
    """
    返回两个数的和。

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

在终端中执行以下命令：

python -m doctest my_module.py -v

输出结果将告知您测试是否通过。

2. 编写 doctest 用例

在这一部分中，我们将学习如何在函数的文档字符串中编写测试用例。

def multiply(a, b):
    """
    返回两个数的乘积。

    >>> multiply(2, 3)
    6
    >>> multiply(5, -1)
    -5
    """
    return a * b

3. 在函数文档字符串中编写测试案例

接下来，我们将深入了解在模块文档字符串中编写测试案例。

"""
这个模块提供了一些数学函数。

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

4. 在模块文档字符串中编写测试案例

有时，我们可能需要在测试中引用其他函数或类。下面是一个例子：

def subtract(a, b):
    """
    返回两个数的差。

    >>> subtract(5, 3)
    2
    >>> subtract(2, 5)
    -3
    >>> add(subtract(5, 3), 10)
    12
    """
    return a - b

5. 运行包含 doctest 的模块或脚本

运行包含 doctest 的模块或脚本非常简单。不需要任何额外的设置或配置。

python -m doctest my_module.py -v

6. 忽略输出结果中的不相干部分

有时，我们需要忽略输出中的某些部分。使用 ==IGNORE== 可以实现这个目的。

def divide(a, b):
    """
    返回两个数的商。

    >>> divide(10, 3)  # doctest: +ELLIPSIS
    3.3...
    >>> divide(5, 0)
    Traceback (most recent call last):
        ...
    ZeroDivisionError: division by zero
    """
    return a / b

7. 使用 `doctest.ELLIPSIS` 忽略部分输出

有时，我们希望忽略输出的一部分并进行比较。doctest.ELLIPSIS 类可以帮助我们实现这个目标。

def divide(a, b):
    """
    返回两个数的商。

    >>> divide(10, 3)  # doctest: +ELLIPSIS
    3.3...
    """
    return a / b

8. 使用 `doctest.NORMALIZE_WHITESPACE` 校正空白字符

doctest.NORMALIZE_WHITESPACE 类可以用于校正空白字符。

def greeting(name):
    """
    打招呼。

    >>> greeting('Alice')
    'Hello, Alice!'
    >>> greeting(' Bob ')
    'Hello, Bob!'
    """
    return f'Hello, {name.strip()}!'

9. 在测试中引用其他函数或类

下面的示例展示了如何在 doctest 中引用其他函数或类。

class Calculator:
    def __init__(self, initial_value):
        self.value = initial_value

    def add(self, num):
        """
        将给定的数添加到当前值上。

        >>> calc = Calculator(10)
        >>> calc.add(5)
        >>> calc.value
        15
        """
        self.value += num

10. 通过 `doctest` 模块中的 API 运行测试

如果需要更多的灵活性，我们可以使用 doctest 模块中的 API 来运行测试。

import doctest

def add(a, b):
    """
    返回两个数的和。

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

doctest.testmod()

结论

在本教程中，我们学习了如何使用 python -m doctest 命令运行 doctest，并通过多个示例演示了如何编写 doctest 用例、在函数和模块文档字符串中编写测试案例、忽略输出结果中的不相干部分以及引用其他函数或类。我们还了解了使用 doctest 模块中的 API 运行测试的方法。

常见问题

doctest 是干什么的？
- doctest 是 Python 的一种测试工具，可以自动提取代码中的文档字符串中的示例，并运行这些示例作为测试。
doctest 如何运行测试？
- 使用 python -m doctest 命令，可以运行包含 doctest 的模块或脚本。
如何忽略输出结果中的不相干部分？
- 使用 ==IGNORE== 可以忽略输出结果中的不相干部分。
如何忽略输出的一部分并进行比较？
- 使用 doctest.ELLIPSIS 类可以实现忽略部分输出的比较。
如何校正空白字符？
- 使用 doctest.NORMALIZE_WHITESPACE 类可以校正空白字符。