良好的集成实践¶

使用 pip 安装包¶

对于开发，我们建议您使用 venv 来创建虚拟环境，并使用 pip 来安装您的应用程序和任何依赖项，以及 pytest 包本身。这确保您的代码和依赖项与您的系统 Python 安装隔离。

在您的仓库根目录中创建 pyproject.toml 文件，如 Packaging Python Projects 中所述。前几行应如下所示

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "PACKAGENAME"
version = "PACKAGEVERSION"

其中 PACKAGENAME 和 PACKAGEVERSION 分别是您包的名称和版本。

然后，您可以从同一目录运行以下命令，以“可编辑”模式安装您的包

pip install -e .

这允许您更改源代码（包括测试和应用程序）并随意重新运行测试。

Python 测试发现约定¶

pytest 实现了以下标准测试发现

如果未指定任何参数，则收集从 testpaths（如果已配置）或当前目录开始。或者，命令行参数可以以目录、文件名或节点 ID 的任意组合使用。
递归进入目录，除非它们匹配 norecursedirs。
在这些目录中，搜索 test_*.py 或 *_test.py 文件，通过它们的测试包名称导入。
从这些文件中，收集测试项
- 以 test 为前缀的类外测试函数或方法。
- 以 test 为前缀的测试函数或方法，位于以 Test 为前缀的测试类中（没有 __init__ 方法）。用 @staticmethod 和 @classmethods 装饰的方法也包括在内。

有关如何自定义测试发现的示例，请参见更改标准（Python）测试发现。

在 Python 模块中，pytest 还使用标准的 unittest.TestCase 子类化技术发现测试。

选择测试布局¶

pytest 支持两种常见的测试布局

应用程序代码之外的测试¶

如果您有许多功能测试或出于其他原因希望将测试与实际应用程序代码分开（通常是个好主意），将测试放入应用程序代码之外的额外目录中可能会很有用

pyproject.toml
src/
    mypkg/
        __init__.py
        app.py
        view.py
tests/
    test_app.py
    test_view.py
    ...

这具有以下好处

在执行 pip install . 后，您的测试可以针对已安装的版本运行。
在执行 pip install --editable . 后，您的测试可以针对本地副本以可编辑安装运行。

对于新项目，我们建议使用 importlib 导入模式（有关详细解释，请参见 which-import-mode）。为此，请在您的配置文件中添加以下内容

# content of pytest.toml
[pytest]
addopts = ["--import-mode=importlib"]

通常，特别是如果您使用默认导入模式 prepend，强烈建议使用 src 布局。在此布局中，您的应用程序根包位于您根目录的子目录中，即 src/mypkg/ 而不是 mypkg。

这种布局避免了许多常见的陷阱，并具有许多好处，这些好处在 Ionel Cristian Mărieș 的这篇优秀的博客文章中有更好的解释。

注意

如果您不使用可编辑安装并使用上述 src 布局，则需要扩展 Python 的模块文件搜索路径，以便直接针对本地副本执行测试。您可以通过设置 PYTHONPATH 环境变量以临时方式进行

PYTHONPATH=src pytest

或者通过使用 pythonpath 配置变量并在您的配置文件中添加以下内容以永久方式进行

toml

[pytest]
pythonpath = ["src"]

ini

[pytest]
pythonpath = src

注意

如果您不使用可编辑安装且不使用 src 布局（mypkg 直接位于根目录中），您可以依赖 Python 默认将当前目录放入 sys.path 来导入您的包，并运行 python -m pytest 以直接针对本地副本执行测试。

有关调用 pytest 和 python -m pytest 之间差异的更多信息，请参见调用 pytest 与 python -m pytest。

作为应用程序代码一部分的测试¶

如果您在测试和应用程序模块之间有直接关系，并且希望将它们与应用程序一起分发，那么将测试目录内联到应用程序包中会很有用

pyproject.toml
[src/]mypkg/
    __init__.py
    app.py
    view.py
    tests/
        __init__.py
        test_app.py
        test_view.py
        ...

在此方案中，使用 --pyargs 选项运行测试非常容易

pytest --pyargs mypkg

pytest 将发现 mypkg 的安装位置并从那里收集测试。

请注意，此布局也与上一节中提到的 src 布局结合使用。

注意

您可以为您的应用程序使用命名空间包 (PEP420)，但 pytest 仍将根据 __init__.py 文件的存在执行测试包名称发现。如果您使用上述两种推荐的文件系统布局之一，但省略了目录中的 __init__.py 文件，它应该能正常工作。但是，从“内联测试”中，您将需要使用绝对导入来获取您的应用程序代码。

注意

在 prepend 和 append 导入模式中，如果 pytest 在递归文件系统时找到 "a/b/test_module.py" 测试文件，它会按如下方式确定导入名称

确定 basedir：这是第一个“向上”（朝向根目录）不包含 __init__.py 的目录。例如，如果 a 和 b 都包含 __init__.py 文件，那么 a 的父目录将成为 basedir。
执行 sys.path.insert(0, basedir) 以使测试模块可以在完全限定的导入名称下导入。
import a.b.test_module，其中路径是通过将路径分隔符 / 转换为“.”字符来确定的。这意味着您必须遵循目录和文件名直接映射到导入名称的约定。

这种有些复杂的导入技术的原因是，在大型项目中，多个测试模块可能会相互导入，因此派生一个规范的导入名称有助于避免诸如测试模块被导入两次等意外情况。

使用 --import-mode=importlib 时，事情不那么复杂，因为 pytest 不需要更改 sys.path，这使得事情更不令人意外。

选择导入模式¶

由于历史原因，pytest 默认使用 prepend 导入模式，而不是我们为新项目推荐的 importlib 导入模式。原因在于 prepend 模式的工作方式

由于没有包可以从中派生完整的包名，pytest 会将您的测试文件作为顶层模块导入。第一个示例 (src 布局) 中的测试文件将通过将 tests/ 添加到 sys.path，作为 test_app 和 test_view 顶层模块导入。

这与 importlib 导入模式相比有一个缺点：您的测试文件必须具有唯一名称。

如果您需要具有相同名称的测试模块，作为一种解决方法，您可以在 tests 文件夹和子文件夹中添加 __init__.py 文件，将它们更改为包

pyproject.toml
mypkg/
    ...
tests/
    __init__.py
    foo/
        __init__.py
        test_view.py
    bar/
        __init__.py
        test_view.py

现在 pytest 将模块加载为 tests.foo.test_view 和 tests.bar.test_view，允许您拥有同名模块。但现在这引入了一个微妙的问题：为了从 tests 目录加载测试模块，pytest 将仓库的根目录添加到 sys.path 的前面，这会产生副作用，即现在 mypkg 也可以导入。

如果您正在使用像 tox 这样的工具在虚拟环境中测试您的包，这会成为问题，因为您希望测试您的包的已安装版本，而不是仓库中的本地代码。

importlib 导入模式没有上述任何缺点，因为导入测试模块时 sys.path 不会更改。

tox¶

完成工作并确保实际包通过所有测试后，您可能需要了解 tox，这个虚拟环境测试自动化工具。tox 帮助您使用预定义的依赖项设置虚拟环境，然后使用选项执行预配置的测试命令。它将针对已安装的包运行测试，而不是针对您的源代码检出，这有助于检测打包故障。

不要通过 setuptools 运行¶

不建议与 setuptools 集成，即您不应使用 python setup.py test 或 pytest-runner，并且将来可能会停止工作。

这已被弃用，因为它依赖于 setuptools 的弃用功能，并依赖于破坏 pip 安全机制的功能。例如，“setup_requires”和“tests_require”绕过 pip --require-hashes。有关更多信息和迁移说明，请参阅 pytest-runner 公告。另请参见 pypa/setuptools#1684。

setuptools 打算移除测试命令。

使用 flake8-pytest-style 检查¶

为了确保在您的项目中正确使用 pytest，使用 flake8-pytest-style flake8 插件可能会有所帮助。

flake8-pytest-style 检查 pytest 代码中常见的错误和编码风格违规，例如 fixture 的不正确使用、测试函数名称和标记。通过使用此插件，您可以在开发过程的早期捕获这些错误，并确保您的 pytest 代码一致且易于维护。

flake8-pytest-style 检测到的 lint 列表可以在其 PyPI 页面上找到。

注意

flake8-pytest-style 不是官方的 pytest 项目。某些规则强制执行某些样式选择，例如使用 @pytest.fixture() 而不是 @pytest.fixture，但您可以配置插件以适应您偏好的样式。

使用 pytest 的严格模式¶

9.0 版本新增。

Pytest 包含一组配置选项，使其更加严格。这些选项默认是关闭的，出于兼容性或其他原因，但如果可以的话，您应该启用它们。

您可以通过设置 strict 配置选项一次性启用所有严格性选项

toml

[pytest]
strict = true

ini

[pytest]
strict = true

有关其启用的选项及其影响，请参见 strict 文档。

如果 pytest 将来添加新的严格性选项，它们也将在严格模式下启用。因此，您应该仅在使用固定/锁定版本的 pytest 时，或者如果您希望主动采用新添加的严格性选项时才启用严格模式。如果您不想自动获取新选项，可以单独启用选项

toml

[pytest]
strict_config = true
strict_markers = true
strict_parametrization_ids = true
strict_xfail = true

ini

[pytest]
strict_config = true
strict_markers = true
strict_parametrization_ids = true
strict_xfail = true

如果您想使用严格模式但某个特定选项有问题，可以单独将其关闭

toml

[pytest]
strict = true
strict_parametrization_ids = false

ini

[pytest]
strict = true
strict_parametrization_ids = false