如何运行 doctests¶
默认情况下，所有匹配 test*.txt 模式的文件都将通过 python 标准 doctest 模块运行。您可以通过发出以下命令来更改模式
pytest --doctest-glob="*.rst"
在命令行中。--doctest-glob 可以在命令行中多次给出。
如果您有一个像这样的文本文件
# content of test_example.txt
hello this is a doctest
>>> x = 3
>>> x
3
那么您可以直接调用 pytest
$ pytest
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y
rootdir: /home/sweet/project
collected 1 item
test_example.txt . [100%]
============================ 1 passed in 0.12s =============================
默认情况下，pytest 将收集 test*.txt 文件以查找 doctest 指令，但您可以使用 --doctest-glob 选项（允许多次）传递其他 glob。
除了文本文件，您还可以直接从类和函数的文档字符串中执行 doctests，包括来自测试模块的 doctests
# content of mymodule.py
def something():
"""a doctest in a docstring
>>> something()
42
"""
return 42
$ pytest --doctest-modules
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y
rootdir: /home/sweet/project
collected 2 items
mymodule.py . [ 50%]
test_example.txt . [100%]
============================ 2 passed in 0.12s =============================
您可以通过将这些更改放入如下所示的 pytest.ini 文件中，使这些更改在您的项目中永久生效
# content of pytest.ini
[pytest]
addopts = --doctest-modules
编码¶
默认编码是 UTF-8，但您可以使用 doctest_encoding ini 选项指定将用于这些 doctest 文件的编码
# content of pytest.ini
[pytest]
doctest_encoding = latin1
使用 ‘doctest’ 选项¶
Python 的标准 doctest 模块提供了一些 选项 来配置 doctest 测试的严格性。在 pytest 中，您可以使用配置文件启用这些标志。
例如，要使 pytest 忽略尾随空格并忽略冗长的异常堆栈跟踪，您可以直接编写
[pytest]
doctest_optionflags = NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL
或者，可以通过 doctest 本身的内联注释来启用选项
>>> something_that_raises() # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
ValueError: ...
pytest 还引入了新选项
ALLOW_UNICODE：启用后，u前缀将从预期 doctest 输出中的 unicode 字符串中剥离。这允许 doctests 在 Python 2 和 Python 3 中不变地运行。ALLOW_BYTES：类似地，b前缀将从预期 doctest 输出中的字节字符串中剥离。NUMBER：启用后，浮点数只需要与您在预期 doctest 输出中写入的精度相匹配。数字使用pytest.approx()进行比较，相对容差等于精度。例如，以下输出在将3.14与pytest.approx(math.pi, rel=10**-2)进行比较时，只需要匹配到小数点后 2 位>>> math.pi 3.14
如果您写入
3.1416，那么实际输出将需要匹配到大约小数点后 4 位；依此类推。这避免了由有限的浮点精度引起的误报，例如
Expected: 0.233 Got: 0.23300000000000001
NUMBER还支持浮点数列表 – 实际上，它匹配输出中任何位置出现的浮点数，甚至在字符串内部！这意味着全局启用doctest_optionflags在您的配置文件中可能不合适。在 5.1 版本中添加。
失败时继续¶
默认情况下，pytest 只会报告给定 doctest 的第一个失败。如果您希望即使在出现失败时也继续测试，请执行
pytest --doctest-modules --doctest-continue-on-failure
输出格式¶
您可以使用标准 doctest 模块格式中的选项更改 doctest 失败时的差异输出格式（请参阅 doctest.REPORT_UDIFF, doctest.REPORT_CDIFF, doctest.REPORT_NDIFF, doctest.REPORT_ONLY_FIRST_FAILURE)
pytest --doctest-modules --doctest-report none
pytest --doctest-modules --doctest-report udiff
pytest --doctest-modules --doctest-report cdiff
pytest --doctest-modules --doctest-report ndiff
pytest --doctest-modules --doctest-report only_first_failure
pytest 特有功能¶
提供了一些功能，以使编写 doctests 更容易，或者更好地与您现有的测试套件集成。但请记住，通过使用这些功能，您将使您的 doctests 与标准 doctests 模块不兼容。
使用 fixtures¶
可以使用 getfixture 助手来使用 fixtures
# content of example.rst
>>> tmp = getfixture('tmp_path')
>>> ...
>>>
请注意，fixture 需要在 pytest 可见的位置定义，例如，conftest.py 文件或插件；除非通过 python_files 显式配置，否则通常不会扫描包含文档字符串的普通 python 文件以查找 fixtures。
此外，执行文本 doctest 文件时，支持 usefixtures 标记和标记为 autouse 的 fixtures。
‘doctest_namespace’ fixture¶
doctest_namespace fixture 可用于将项目注入到您的 doctests 运行的命名空间中。它旨在在您自己的 fixtures 中使用，以便为使用它们的测试提供上下文。
doctest_namespace 是一个标准的 dict 对象，您可以将想要出现在 doctest 命名空间中的对象放入其中
# content of conftest.py
import pytest
import numpy
@pytest.fixture(autouse=True)
def add_np(doctest_namespace):
doctest_namespace["np"] = numpy
然后可以在您的 doctests 中直接使用
# content of numpy.py
def arange():
"""
>>> a = np.arange(10)
>>> len(a)
10
"""
请注意，与普通的 conftest.py 一样，fixtures 是在 conftest 所在的目录树中发现的。这意味着如果您将 doctest 与源代码放在一起，则相关的 conftest.py 需要位于同一目录树中。不会在同级目录树中发现 Fixtures！
跳过测试¶
出于与可能想要跳过普通测试相同的原因，也可以跳过 doctests 内的测试。
要跳过 doctest 中的单个检查，您可以使用标准 doctest.SKIP 指令
def test_random(y):
"""
>>> random.random() # doctest: +SKIP
0.156231223
>>> 1 + 1
2
"""
这将跳过第一个检查，但不跳过第二个。
pytest 还允许在 doctests 内部使用标准 pytest 函数 pytest.skip() 和 pytest.xfail()，这可能很有用，因为您可以根据外部条件跳过/xfail 测试
>>> import sys, pytest
>>> if sys.platform.startswith('win'):
... pytest.skip('this doctest does not work on Windows')
...
>>> import fcntl
>>> ...
但是，不鼓励使用这些函数，因为它会降低文档字符串的可读性。
注意
pytest.skip() 和 pytest.xfail() 的行为因 doctests 是在 Python 文件（在文档字符串中）还是在包含与文本混合的 doctests 的文本文件中而异
Python 模块（文档字符串）：这些函数仅在该特定文档字符串中起作用，让同一模块中的其他文档字符串正常执行。
文本文件：这些函数将跳过/xfail 整个文件中其余部分的检查。
替代方案¶
虽然内置的 pytest 支持为使用 doctests 提供了一组良好的功能，但如果您广泛使用它们，您可能会对那些添加更多功能的外部软件包感兴趣，并包括 pytest 集成
pytest-doctestplus：提供高级 doctest 支持，并启用 reStructuredText (“.rst”) 文件的测试。
Sybil：提供了一种通过从文档源解析示例并将解析后的示例评估为正常测试运行的一部分来测试文档中示例的方法。