配置

命令行选项和配置文件设置

您可以使用通用帮助选项获取命令行和配置选项的帮助

pytest -h   # prints options _and_ config file settings

这将显示已安装插件注册的命令行和配置文件设置。

配置文件格式

许多 pytest 设置 可以在 配置文件 中设置，按照惯例，该文件位于仓库的根目录中。

一个快速示例，展示 pytest 支持的配置文件

pytest.toml

9.0 版本新增。

pytest.toml 文件优先于其他文件，即使是空文件。

或者，可以使用隐藏版本 .pytest.toml。

# pytest.toml or .pytest.toml
[pytest]
minversion = "9.0"
addopts = ["-ra", "-q"]
testpaths = [
    "tests",
    "integration",
]

pytest.ini

pytest.ini 文件优先于其他文件（pytest.toml 和 .pytest.toml 除外），即使是空文件。

或者，可以使用隐藏版本 .pytest.ini。

# pytest.ini or .pytest.ini
[pytest]
minversion = 6.0
addopts = -ra -q
testpaths =
    tests
    integration

pyproject.toml

6.0 版本新增。

版本 9.0 中已更改。

支持 pyproject.toml 文件进行配置。

使用 [tool.pytest] 来利用原生的 TOML 类型（自 pytest 9.0 起支持）

# pyproject.toml
[tool.pytest]
minversion = "9.0"
addopts = ["-ra", "-q"]
testpaths = [
    "tests",
    "integration",
]

使用 [tool.pytest.ini_options] 进行 INI 风格的配置（自 pytest 6.0 起支持）

# pyproject.toml
[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-ra -q"
testpaths = [
    "tests",
    "integration",
]

tox.ini

tox.ini 文件是 tox 项目的配置文件，如果它们有 [pytest] 部分，也可以用于保存 pytest 配置。

# tox.ini
[pytest]
minversion = 6.0
addopts = -ra -q
testpaths =
    tests
    integration

setup.cfg

setup.cfg 文件是通用配置文件，最初由 distutils（现已弃用）和 setuptools 使用，如果它们有 [tool:pytest] 部分，也可以用于保存 pytest 配置。

# setup.cfg
[tool:pytest]
minversion = 6.0
addopts = -ra -q
testpaths =
    tests
    integration

警告

不建议使用 setup.cfg，除非是对于非常简单的用例。.cfg 文件使用的解析器与 pytest.ini 和 tox.ini 不同，这可能会导致难以追踪的问题。如果可能，建议使用后者文件，或 pyproject.toml，来保存您的 pytest 配置。

初始化：确定根目录和配置文件

pytest 为每次测试运行确定一个 rootdir，这取决于命令行参数（指定的测试文件、路径）和配置文件的存在。确定的 rootdir 和 configfile 在启动时作为 pytest 头部的一部分打印出来。

下面是 pytest 使用 rootdir 的总结

  • 在收集过程中构建 nodeids；每个测试都被分配一个唯一的 nodeid，该 nodeid 以 rootdir 为根，并考虑完整的路径、类名、函数名和参数化（如果有）。

  • 被插件用作一个稳定的位置，用于存储项目/测试运行的特定信息；例如，内部的 缓存 插件在 rootdir 中创建一个 .pytest_cache 子目录来存储其跨测试运行状态。

rootdir 不 用于修改 sys.path/PYTHONPATH 或影响模块的导入。有关更多详细信息，请参阅 pytest 导入机制和 sys.path/PYTHONPATH。

命令行选项 --rootdir=path 可用于强制指定一个目录。请注意，与其他命令行选项相反，--rootdir 不能与配置文件中的 addopts 一起使用，因为 rootdir 已用于 查找 配置文件。

查找 rootdir

这是从 args 查找 rootdir 的算法

  • 如果在命令行中传递了 -c，则将其用作配置文件，并将其目录用作 rootdir。

  • 确定指定为文件系统中存在的路径的 args 的共同祖先目录。如果未找到此类路径，则将共同祖先目录设置为当前工作目录。

  • 在祖先目录及向上查找 pytest.toml、.pytest.toml、pytest.ini、.pytest.ini、pyproject.toml、tox.ini 和 setup.cfg 文件。如果找到匹配项，则该文件成为 configfile，其目录成为 rootdir。

  • 如果未找到配置文件，则从共同祖先目录向上查找 setup.py 以确定 rootdir。

  • 如果未找到 setup.py，则在每个指定的 args 及向上查找 pytest.toml、.pytest.toml、pytest.ini、.pytest.ini、pyproject.toml、tox.ini 和 setup.cfg。如果找到匹配项，则该文件成为 configfile，其目录成为 rootdir。

  • 如果没有找到 configfile 并且没有传递配置参数，则使用已确定的共同祖先作为根目录。这允许在不属于包且没有任何特定配置文件的结构中使用 pytest。

如果没有给出 args，pytest 会收集当前工作目录下的测试，并从那里开始确定 rootdir。

文件只有在以下情况下才会被匹配为配置

  • pytest.toml：始终匹配并具有最高优先级，即使为空。

  • pytest.ini：始终匹配并具有优先级（在 pytest.toml 和 .pytest.toml 之后），即使为空。

  • pyproject.toml：包含 [tool.pytest] 或 [tool.pytest.ini_options] 表。

  • tox.ini：包含 [pytest] 部分。

  • setup.cfg：包含 [tool:pytest] 部分。

最后，如果没有找到其他匹配项，pyproject.toml 文件将被视为 configfile，即使它不包含 [tool.pytest] 表（自版本 9.0 起）或 [tool.pytest.ini_options] 表（自版本 8.1 起）。

文件按上述顺序考虑。来自多个 configfiles 候选者的选项绝不合并——第一个匹配的获胜。

配置文件还决定 rootpath 的值。

Config 对象（可通过钩子或通过 pytestconfig 夹具访问）随后将包含这些属性

  • config.rootpath：确定的根目录，保证存在。它用作构建测试地址（“nodeids”）的参考目录，也可供插件用于存储每次测试运行的信息。

  • config.inipath：确定的 configfile，可能为 None（因历史原因命名为 inipath）。

版本 6.1 中新增：config.rootpath 和 config.inipath 属性。它们是旧版 config.rootdir 和 config.inifile 的 pathlib.Path 版本，这些旧版属性类型为 py.path.local，并为了向后兼容而仍然存在。

示例

pytest path/to/testdir path/other/

将确定共同祖先为 path，然后按如下方式检查配置文件

# first look for path/pytest.toml
path/pytest.toml
path/pytest.ini
path/pyproject.toml  # must contain a [tool.pytest] table to match
path/tox.ini         # must contain [pytest] section to match
path/setup.cfg       # must contain [tool:pytest] section to match
pytest.toml
pytest.ini
... # all the way up to the root

# now look for setup.py
path/setup.py
setup.py
... # all the way up to the root

警告

自定义 pytest 插件命令行参数可能包含路径，例如 pytest --log-output ../../test.log args。然后 args 是强制性的，否则 pytest 会使用 test.log 所在的文件夹来确定 rootdir（另请参阅 #1435）。点 . 也可以用于引用当前工作目录。

内置配置文件选项

有关所有选项的完整列表，请查阅 参考文档。

语法高亮主题定制

pytest 使用的语法高亮主题可以通过两个环境变量进行定制