配置

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

您可以使用通用帮助选项获取有关 INI 风格配置文件中命令行选项和值的帮助

pytest -h   # prints options _and_ config file settings

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

配置文件格式

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

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

pytest.ini

pytest.ini 文件优先于其他文件，即使文件为空。

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

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

pyproject.toml

在 6.0 版本中添加。

当 pyproject.toml 包含 tool.pytest.ini_options 表时，将被视为配置文件。

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

注意

人们可能想知道为什么是 [tool.pytest.ini_options] 而不是像其他工具一样使用 [tool.pytest]。

原因是 pytest 团队计划将来充分利用丰富的 TOML 数据格式进行配置，保留 [tool.pytest] 表用于此目的。ini_options 表现在用作现有 .ini 配置系统和未来配置格式之间的桥梁。

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 v76.0.0.post20250309)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 配置。

初始化：确定 rootdir 和 configfile

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

以下是 pytest 使用 rootdir 的摘要

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

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

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

--rootdir=path 命令行选项可用于强制指定目录。请注意，与其他命令行选项相反，--rootdir 不能与 addopts 在 pytest.ini 中一起使用，因为 rootdir 用于查找 pytest.ini。

查找 rootdir

这是从 args 查找 rootdir 的算法

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

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

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

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

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

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

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

仅当满足以下条件时，文件才会被匹配为配置文件

  • pytest.ini：将始终匹配并优先，即使为空。

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

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

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

最后，如果没有找到其他匹配项，则 pyproject.toml 文件将被视为 configfile，在这种情况下，即使它不包含 [tool.pytest.ini_options] 表（这是在 8.1 中添加的）。

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

配置文件还确定 rootpath 的值。

Config 对象（可通过 hooks 或通过 pytestconfig fixture 访问）随后将携带这些属性

  • 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 pytest.ini files
path/pytest.ini
path/pyproject.toml  # must contain a [tool.pytest.ini_options] table to match
path/tox.ini         # must contain [pytest] section to match
path/setup.cfg       # must contain [tool:pytest] section to match
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 使用的语法高亮主题可以使用两个环境变量进行自定义