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 自动发现。

    它的工作原理如下

    1. 给定一个模块路径,例如 tests/core/test_models.py,推导出规范名称,如 tests.core.test_models,并尝试导入。

      对于非测试模块,如果它们可以通过 sys.path 访问,这将起作用。例如,.env/lib/site-packages/app/core.py 将可作为 app.core 导入。当插件导入非测试模块时(例如 doctesting),就会发生这种情况。

      如果此步骤成功,则返回该模块。

      对于测试模块,除非它们可从 sys.path 访问,否则此步骤将失败。

    2. 如果上一步失败,我们直接使用 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 配置变量进行更改。

另请参阅

pythonpath 配置变量。

consider_namespace_packages 配置变量。

选择测试布局.

prependappend 导入模式场景

以下是使用 prependappend 导入模式时的场景列表,其中 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 测试发现约定 中也有详细讨论。

调用 pytestpython -m pytest

使用 pytest [...] 而不是 python -m pytest [...] 运行 pytest 会产生几乎相同的行为,不同之处在于后者会将当前目录添加到 sys.path,这是标准的 python 行为。

另请参阅 通过 python -m pytest 调用 pytest