编写 hook 函数¶
hook 函数验证和执行¶
pytest 从注册的插件中为任何给定的 hook 规范调用 hook 函数。让我们看一下 pytest_collection_modifyitems(session, config, items) hook 的典型 hook 函数，pytest 在完成所有测试项的收集后调用它。
当我们在插件中实现 pytest_collection_modifyitems 函数时，pytest 将在注册期间验证您使用的参数名称是否与规范匹配，如果不匹配则会中止。
让我们看一个可能的实现
def pytest_collection_modifyitems(config, items):
# called after collection is completed
# you can modify the ``items`` list
...
在这里，pytest 将传入 config (pytest 配置对象) 和 items (收集的测试项列表)，但不会传入 session 参数，因为我们没有在函数签名中列出它。这种参数的动态“修剪”允许 pytest “未来兼容”：我们可以引入新的 hook 命名参数，而不会破坏现有 hook 实现的签名。这是 pytest 插件普遍长期兼容性的原因之一。
请注意，除了 pytest_runtest_* 之外的 hook 函数不允许引发异常。这样做会破坏 pytest 运行。
firstresult：在第一个非 None 结果处停止¶
大多数对 pytest hooks 的调用都会产生一个 结果列表，其中包含所有被调用 hook 函数的非 None 结果。
一些 hook 规范使用 firstresult=True 选项，以便 hook 调用仅执行到 N 个注册函数中的第一个返回非 None 结果为止，然后将其作为整个 hook 调用的结果。在这种情况下，其余的 hook 函数将不会被调用。
hook 包装器：围绕其他 hooks 执行¶
pytest 插件可以实现 hook 包装器，它包装其他 hook 实现的执行。hook 包装器是一个生成器函数，它只 yield 一次。当 pytest 调用 hooks 时，它首先执行 hook 包装器，并传递与常规 hooks 相同的参数。
在 hook 包装器的 yield 点，pytest 将执行下一个 hook 实现，并将其结果返回到 yield 点，或者如果它们引发异常，则会传播异常。
这是一个 hook 包装器的示例定义
import pytest
@pytest.hookimpl(wrapper=True)
def pytest_pyfunc_call(pyfuncitem):
do_something_before_next_hook_executes()
# If the outcome is an exception, will raise the exception.
res = yield
new_res = post_process_result(res)
# Override the return value to the plugin system.
return new_res
hook 包装器需要为 hook 返回一个结果，或引发一个异常。
在许多情况下，包装器只需要在实际的 hook 实现周围执行跟踪或其他副作用，在这种情况下，它可以返回 yield 的结果值。最简单（但无用）的 hook 包装器是 return (yield)。
在其他情况下，包装器想要调整或适应结果，在这种情况下，它可以返回一个新值。如果底层 hook 的结果是一个可变对象，包装器可能会修改该结果，但最好避免这样做。
如果 hook 实现因异常而失败，包装器可以使用 try-catch-finally 围绕 yield 来处理该异常，通过传播它、抑制它或引发完全不同的异常。
有关更多信息，请查阅 关于 hook 包装器的 pluggy 文档。
Hook 函数排序 / 调用示例¶
对于任何给定的 hook 规范，可能存在多个实现，因此我们通常将 hook 执行视为 1:N 函数调用，其中 N 是注册函数的数量。有一些方法可以影响 hook 实现是在其他实现之前还是之后执行，即在 N 大小的函数列表中的位置
# Plugin 1
@pytest.hookimpl(tryfirst=True)
def pytest_collection_modifyitems(items):
# will execute as early as possible
...
# Plugin 2
@pytest.hookimpl(trylast=True)
def pytest_collection_modifyitems(items):
# will execute as late as possible
...
# Plugin 3
@pytest.hookimpl(wrapper=True)
def pytest_collection_modifyitems(items):
# will execute even before the tryfirst one above!
try:
return (yield)
finally:
# will execute after all non-wrappers executed
...
这是执行顺序
Plugin3 的 pytest_collection_modifyitems 被调用直到 yield 点，因为它是一个 hook 包装器。
Plugin1 的 pytest_collection_modifyitems 被调用，因为它被标记为
tryfirst=True。Plugin2 的 pytest_collection_modifyitems 被调用，因为它被标记为
trylast=True（即使没有此标记，它也会在 Plugin1 之后执行）。Plugin3 的 pytest_collection_modifyitems 然后执行 yield 点之后的代码。yield 接收来自调用非包装器的结果，或者如果非包装器引发异常，则引发异常。
也可以在 hook 包装器上使用 tryfirst 和 trylast，在这种情况下，它将影响 hook 包装器之间的排序。
声明新的 hooks¶
注意
这是一个关于如何添加新 hooks 以及它们如何工作的快速概述，但更完整的概述可以在 pluggy 文档中找到。
插件和 conftest.py 文件可以声明新的 hooks，然后可以由其他插件实现这些 hooks，以便更改行为或与新插件交互
- pytest_addhooks(pluginmanager)[source]
在插件注册时调用，以允许通过调用
pluginmanager.add_hookspecs(module_or_class, prefix)添加新的 hooks。- 参数:
pluginmanager (PytestPluginManager) – pytest 插件管理器。
注意
此 hook 与 hook 包装器不兼容。
在 conftest 插件中使用¶
如果 conftest 插件实现了此 hook，则在注册 conftest 时将立即调用它。
Hooks 通常声明为无操作函数，这些函数仅包含描述何时调用 hook 以及期望的返回值的文档。函数的名称必须以 pytest_ 开头，否则 pytest 将无法识别它们。
这是一个例子。假设此代码位于 sample_hook.py 模块中。
def pytest_my_hook(config):
"""
Receives the pytest config and does things with it
"""
要向 pytest 注册 hooks，它们需要以自己的模块或类进行结构化。然后可以使用 pytest_addhooks 函数（它本身是 pytest 公开的 hook）将此类或模块传递给 pluginmanager。
def pytest_addhooks(pluginmanager):
"""This example assumes the hooks are grouped in the 'sample_hook' module."""
from my_app.tests import sample_hook
pluginmanager.add_hookspecs(sample_hook)
对于真实世界的示例，请参阅来自 xdist 的 newhooks.py。
Hooks 可以从 fixtures 或其他 hooks 中调用。在这两种情况下，hooks 都是通过 hook 对象调用的，该对象在 config 对象中可用。大多数 hooks 直接接收 config 对象，而 fixtures 可以使用提供相同对象的 pytestconfig fixture。
@pytest.fixture()
def my_fixture(pytestconfig):
# call the hook called "pytest_my_hook"
# 'result' will be a list of return values from all registered functions.
result = pytestconfig.hook.pytest_my_hook(config=pytestconfig)
注意
Hooks 仅使用关键字参数接收参数。
现在您的 hook 已准备好使用。要向 hook 注册一个函数，其他插件或用户现在只需在其 conftest.py 中使用正确的签名定义函数 pytest_my_hook。
示例
def pytest_my_hook(config):
"""
Print all active hooks to the screen.
"""
print(config.hook)
在 pytest_addoption 中使用 hooks¶
有时，有必要根据另一个插件中的 hooks 更改一个插件定义命令行选项的方式。例如，一个插件可能会公开一个命令行选项，另一个插件需要为其定义默认值。可以使用 pluginmanager 安装和使用 hooks 来完成此操作。插件将定义并添加 hooks，并按如下方式使用 pytest_addoption
# contents of hooks.py
# Use firstresult=True because we only want one plugin to define this
# default value
@hookspec(firstresult=True)
def pytest_config_file_default_value():
"""Return the default value for the config file command line option."""
# contents of myplugin.py
def pytest_addhooks(pluginmanager):
"""This example assumes the hooks are grouped in the 'hooks' module."""
from . import hooks
pluginmanager.add_hookspecs(hooks)
def pytest_addoption(parser, pluginmanager):
default_value = pluginmanager.hook.pytest_config_file_default_value()
parser.addoption(
"--config-file",
help="Config file to use, defaults to %(default)s",
default=default_value,
)
使用 myplugin 的 conftest.py 将简单地按如下方式定义 hook
def pytest_config_file_default_value():
return "config.yaml"
可选地使用来自第三方插件的 hooks¶
如上所述，使用来自插件的新 hooks 可能有点棘手，因为标准的 验证机制：如果您依赖于未安装的插件，验证将失败，并且错误消息对您的用户来说意义不大。
一种方法是将 hook 实现推迟到一个新插件，而不是直接在插件模块中声明 hook 函数，例如
# contents of myplugin.py
class DeferPlugin:
"""Simple plugin to defer pytest-xdist hook functions."""
def pytest_testnodedown(self, node, error):
"""standard xdist hook function."""
def pytest_configure(config):
if config.pluginmanager.hasplugin("xdist"):
config.pluginmanager.register(DeferPlugin())
这样做的好处是允许您根据安装了哪些插件有条件地安装 hooks。
在跨 hook 函数的项目上存储数据¶
插件通常需要在 hook 实现中将数据存储在 Item s 上，并在另一个 hook 实现中访问它。一种常见的解决方案是直接在项目上分配一些私有属性，但像 mypy 这样的类型检查器对此表示不满，并且它也可能导致与其他插件冲突。因此，pytest 提供了一种更好的方法来做到这一点，item.stash。
要在插件中使用“stash”，首先在插件的顶层某处创建“stash 键”
been_there_key = pytest.StashKey[bool]()
done_that_key = pytest.StashKey[str]()
然后在某个时候使用键来 stash 您的数据
def pytest_runtest_setup(item: pytest.Item) -> None:
item.stash[been_there_key] = True
item.stash[done_that_key] = "no"
并在另一个时候检索它们
def pytest_runtest_teardown(item: pytest.Item) -> None:
if not item.stash[been_there_key]:
print("Oh?")
item.stash[done_that_key] = "yes!"