配置

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

您可以使用通用帮助选项获取有关命令行选项和 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 使用，如果它们包含 [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 不能与 pytest.ini 中的addopts 一起使用，因为 rootdir 已经用于查找 pytest.ini。

查找 rootdir

以下是根据 args 查找 rootdir 的算法：

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

  • 确定指定为文件系统中存在的路径的 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 对象（可通过 hook 或 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 使用的语法高亮主题可以通过两个环境变量进行自定义：