pytest-doctestplus 1.2.1

设置和配置

此插件提供三个命令行选项：--doctest-plus 用于启用上述高级功能，--doctest-rst 用于将 *.rst 文件包含在 doctest 收集中，以及 --doctest-ufunc 用于将 doctests 包含在 Numpy ufunc 的文档字符串中。

还可以通过将 doctest_plus = enabled 添加到包的 setup.cfg 文件的 [tool:pytest] 部分来默认启用此插件。

此插件应用于 pytest 收集的所有目录和文件。这意味着在 setup.cfg 中配置 testpaths 和 norecursedirs 也会影响 pytest-doctestplus 将发现的文件。此外，此插件还提供了一个 doctest_norecursedirs 配置变量，它指示应被 pytest-doctestplus 忽略但不需要被其他 pytest 功能忽略的目录。

使用 pytest 内置的 --doctest-modules 选项将覆盖此插件的行为，即使 setup.cfg 中有 doctest_plus = enabled，也将导致使用默认的 doctest 插件。但是，如果由于某些原因同时提供了 --doctest-modules 和 --doctest-plus，则无论 setup.cfg 的内容如何，都将使用 pytest-doctestplus 插件。

pytest-doctestplus 遵守 --doctest-continue-on-failure 标志。如果设置，doctest 将会报告所有失败的行，这有助于检测同一个 doctest 中的独立错误。然而，如果早期失败导致后续行访问的变量保持未设置或具有意外的值，这可能会生成假阳性。

此插件遵守内置 doctest 插件使用的 doctest 选项，并在 setup.cfg 中的 doctest_optionflags 中设置。默认情况下，使用 ELLIPSIS 和 NORMALIZE_WHITESPACE。有关所有 doctest 设置的描述，请参阅doctest 文档。

在 Markdown 文件中运行测试

要运行 Markdown 文件中的 doctests，请在命令行中使用 --doctest-plus --doctest-glob '*.md' 选项调用 pytest。

如果您在 GitHub 风格的三重反引号代码块 中编写 doctests，那么为了使 pytest-doctest 能够找到并运行它们，您需要在代码块中包含一个额外的尾随换行符，如下所示

```pycon
>>> 1 + 2
2

```

Doctest 指令

pytest-doctestplus 插件定义了用于控制特定功能行为的 doctest 指令。有关指令及其使用的通用信息，请查阅文档。此插件定义的指令的具体内容在下文各节中描述。

Sphinx Doctest 指令

您可以在 Sphinx RST 中使用 testsetup 和 testcleanup 来运行在渲染文档中不可见的代码。然而，由于 pytest-doctestplus 的工作方式，需要在这些代码前面加上 >>>。例如

.. testsetup::

    >>> x = 42

.. testcleanup::

    >>> del x

浮点数比较

某些 doctests 可能会产生包含浮点数值字符串表示的输出。浮点数表示通常不是精确的，并且在最低有效位包含舍入误差。根据测试运行的平台（不同的 Python 版本、不同的操作系统等），显示的确切数字位数可能不同。由于 doctests 通过比较字符串来工作，这可能导致此类测试失败。

为了解决这个问题，pytest-doctestplus 插件提供了对 FLOAT_CMP 标志的支持，该标志可用于 doctests。例如

>>> 1.0 / 3.0  # doctest: +FLOAT_CMP
0.333333333333333311

>>> {'a': 1 / 3., 'b': 2 / 3.}  # doctest: +FLOAT_CMP
{'a': 0.333333, 'b': 0.666666}

当使用此标志时，预期的和实际的输出都被解析以查找字符串中的任何浮点值。然后，将它们转换为实际的 Python float 对象，并进行数值比较。这意味着舍入数字表示中的小差异将被 doctest 忽略。值的其他部分将被精确比较，因此更显著的（尽管可能是小的）差异仍会被这些测试捕获。

可以通过将其添加到 setup.cfg 中来全局启用此标志，如下所示

doctest_optionflags =
    NORMALIZE_WHITESPACE
    ELLIPSIS
    FLOAT_CMP

忽略警告

如果 doctest 中的代码发出警告，并且您想要确保该警告被静默处理，则可以使用 IGNORE_WARNINGS 标志。例如

>>> import numpy as np
>>> np.mean([])  # doctest: +IGNORE_WARNINGS
np.nan

显示警告

如果在doctest中的代码发出警告，并且您想确保显示该警告，则可以使用SHOW_WARNINGS标志。当pytest将警告转换为错误，并且默认情况下警告被打印到stderr时，这很有用。这与IGNORE_WARNINGS相反，因此显然不应同时使用这两个标志。例如

>>> import numpy as np
>>> np.mean([])  # doctest: +SHOW_WARNINGS
RuntimeWarning: Mean of empty slice.
RuntimeWarning: invalid value encountered in double_scalars
np.nan

跳过测试

Doctest提供了+SKIP指令，用于在测试文档时跳过不应执行的语句。

>>> open('file.txt') # doctest: +SKIP

在Sphinx .rst文档中，可以使用指令跳过整个代码示例块。

.. doctest-skip::

    >>> import asdf
    >>> asdf.open('file.asdf')

然而，通常能够跳过与特定函数、方法、类或整个文件关联的文档字符串非常有用。

.. doctest-skip-all

   >>> import non_existing
   >>> non_existing.write_pseudo_code()
   All the doctests are skipped in the file below

__doctest_skip__ = ['myfunction', 'MyClass', 'MyClass.*']

__doctest_skip__  = ['.', 'myfunction', 'MyClass']

__doctest_skip__ = ['*']

__doctest_requires__ = {('func1', 'func2'): ['scipy']}

.. doctest-requires:: asdf

    >>> import asdf
    >>> asdf.open('file.asdf')

.. doctest-requires:: asdf<3

    >>> import asdf
    >>> asdf.open('file.asdf')

doctest_subpackage_requires =
    astropy/wcs/* = scipy>2.0;numpy>1.14
    astropy/cosmology/* = scipy>1.0

远程数据

“pytest-doctestplus”插件可以与pytest-remotedata插件一起使用，以控制需要访问互联网数据的doctest代码。为了使用这些功能，必须安装pytest-remotedata插件，并使用pytest的--remote-data命令行选项启用远程数据访问。有关更多详细信息，请参阅pytest-remotedata插件文档。

以下示例说明了如何标记使用远程数据的doctest

>>> from urlib.request import urlopen
>>> url = urlopen('http://astropy.org')  # doctest: +REMOTE_DATA

+REMOTE_DATA指令表示，如果提供了--remote-data选项，则应仅执行标记的语句。默认情况下，所有带有远程数据指令标记的语句都将被跳过。

整个代码示例块也可以用这种方式标记，以控制从互联网访问数据

.. doctest-remote-data::

    >>> import requests
    >>> r = requests.get('https://www.astropy.org')

与Sphinx的兼容性

当使用Sphinx构建文档时，您可能需要启用Sphinx扩展，这些扩展将指令注册到Sphinx中。这样做可以确保Sphinx正确忽略这些指令，使用Sphinx运行doctests不受支持。为此，请在您的conf.py文件中将'pytest_doctestplus.sphinx.doctestplus'添加到您的extensions列表中。