pytest 导入机制与 sys.path
/PYTHONPATH
¶
导入模式¶
pytest 作为测试框架,需要导入测试模块和 conftest.py
文件以供执行。
在 Python 中导入文件并非易事,因此可以通过 --import-mode
命令行标志来控制导入过程的某些方面,该标志可以取以下值
prepend
(默认):包含每个模块的目录路径将被插入到sys.path
的开头(如果尚未存在),然后使用importlib.import_module
函数导入。强烈建议通过向包含测试的目录添加
__init__.py
文件来将测试模块组织为包。这将使测试成为一个 proper Python 包的一部分,从而允许 pytest 解析它们的完整名称(例如,tests.core
包内的test_core.py
的完整名称为tests.core.test_core
)。如果测试目录树未组织为包,那么每个测试文件都需要与其它测试文件相比具有唯一名称,否则如果 pytest 发现两个名称相同的测试,它将引发错误。
这是经典机制,可追溯到 Python 2 仍受支持的时期。
append
:包含每个模块的目录将被附加到sys.path
的末尾(如果尚未存在),并使用importlib.import_module
导入。这更好地允许用户针对包的已安装版本运行测试模块,即使被测包具有相同的导入根。例如
testing/__init__.py testing/test_pkg_under_test.py pkg_under_test/
当使用
--import-mode=append
时,测试将针对pkg_under_test
的已安装版本运行,而使用prepend
时,它们会选择本地版本。这种混淆是我们提倡使用 src 布局 的原因。与
prepend
相同,当测试目录树未组织为包时,要求测试模块名称唯一,因为模块导入后会放入sys.modules
中。
importlib
:此模式使用importlib
提供的更精细的控制机制来导入测试模块,而无需更改sys.path
。此模式的优点
pytest 将完全不更改
sys.path
。测试模块名称无需唯一——pytest 将根据
rootdir
自动生成唯一名称。
缺点
测试模块无法相互导入。
测试目录中的测试工具模块(例如包含测试相关函数/类的
tests.helpers
模块)无法导入。在这种情况下,建议将测试工具模块与应用程序/库代码放在一起,例如app.testing.helpers
。重要提示:“测试工具模块”是指被其他测试直接导入的函数/类;这不包括 fixtures,fixtures 应与测试模块一起放置在
conftest.py
文件中,并由 pytest 自动发现。
它的工作原理如下
给定一个模块路径,例如
tests/core/test_models.py
,推导出规范名称,如tests.core.test_models
,并尝试导入。对于非测试模块,如果它们可以通过
sys.path
访问,这将起作用。例如,.env/lib/site-packages/app/core.py
将可作为app.core
导入。当插件导入非测试模块时(例如 doctesting),就会发生这种情况。如果此步骤成功,则返回该模块。
对于测试模块,除非它们可从
sys.path
访问,否则此步骤将失败。如果上一步失败,我们直接使用
importlib
功能导入模块,这允许我们导入它而无需更改sys.path
。因为 Python 要求模块在
sys.modules
中也可用,pytest 根据模块相对于rootdir
的位置为其派生一个唯一名称,并将模块添加到sys.modules
。例如,
tests/core/test_models.py
最终将作为模块tests.core.test_models
导入。
6.0 版本新增。
注意
最初我们打算在未来的版本中将 importlib
作为默认值,然而,现在很明显它有其自身的缺点,因此在可预见的未来,默认值仍将是 prepend
。
注意
默认情况下,pytest 不会自动尝试解析命名空间包,但可以通过 consider_namespace_packages
配置变量进行更改。
prepend
和 append
导入模式场景¶
以下是使用 prepend
或 append
导入模式时的场景列表,其中 pytest 需要更改 sys.path
以导入测试模块或 conftest.py
文件,以及用户可能因此遇到的问题。
包内的测试模块 / conftest.py
文件¶
考虑以下文件和目录布局
root/
|- foo/
|- __init__.py
|- conftest.py
|- bar/
|- __init__.py
|- tests/
|- __init__.py
|- test_foo.py
执行时
pytest root/
pytest 将找到 foo/bar/tests/test_foo.py
并意识到它是一个包的一部分,因为同一文件夹中存在 __init__.py
文件。然后它会向上搜索,直到找到最后一个仍然包含 __init__.py
文件的文件夹,以找到包的根(在本例中为 foo/
)。为了加载该模块,它会将 root/
插入到 sys.path
的开头(如果尚未存在),以便将 test_foo.py
作为模块 foo.bar.tests.test_foo
加载。
同样的逻辑也适用于 conftest.py
文件:它将被导入为 foo.conftest
模块。
当测试位于包中时,保留完整的包名很重要,以避免问题并允许测试模块具有重复的名称。这在 Python 测试发现约定 中也有详细讨论。
独立测试模块 / conftest.py
文件¶
考虑以下文件和目录布局
root/
|- foo/
|- conftest.py
|- bar/
|- tests/
|- test_foo.py
执行时
pytest root/
pytest 将找到 foo/bar/tests/test_foo.py
并意识到它不是包的一部分,因为同一文件夹中没有 __init__.py
文件。然后它会将 root/foo/bar/tests
添加到 sys.path
,以便将 test_foo.py
作为模块 test_foo
导入。对于 conftest.py
文件也一样,通过将 root/foo
添加到 sys.path
来将其导入为 conftest
。
因此,这种布局不能有同名的测试模块,因为它们都将被导入到全局导入命名空间中。
这在 Python 测试发现约定 中也有详细讨论。
调用 pytest
与 python -m pytest
¶
使用 pytest [...]
而不是 python -m pytest [...]
运行 pytest 会产生几乎相同的行为,不同之处在于后者会将当前目录添加到 sys.path
,这是标准的 python 行为。