说实话我开始认真读pytest源码并不是因为好奇而是被两个实际问题逼的。第一个问题同事在项目里同时装了pytest-ordering和pytest-randomly结果排序完全失效测试用例顺序跟随机数生成器似的怎么都调不回来。第二个问题我写了一个插件想在pytest_terminal_summary里追加一份自检报告但输出内容总被另一个第三方插件提前截断少了一截。这俩问题表面上叫插件冲突、插件不生效但追到根上全落在pytest插件系统同一段机制里插件是被谁发现的、以什么名字注册的、钩子实现按什么顺序执行。换句话说只要把源码走一遍这类问题基本都能自己定位不用再去翻issue和stackoverflow碰运气。这篇文章不是教你怎么写一个插件demo而是顺着pytest的启动链路把插件系统从发现插件到执行钩子的关键源码拆开讲清楚。读完你至少能回答三个问题第三方插件为什么装完就能生效pytest.hookimpl到底在函数上做了什么为什么你写的pytest_collection_modifyitems有时候排在别人后面1. 插件系统的三条主线发现、注册、调用1.1 两个让我抓狂的真实场景以及它们指向的源码位置先回来说那两个问题。pytest-ordering和pytest-randomly同时存在时pytest-randomly默认会对测试顺序做随机化而pytest-ordering想通过pytest.mark.run这类标记来固化顺序。问题在于两个插件都在监听同一个钩子pytest_collection_modifyitems一个要打乱一个要排固定序最后谁生效完全由钩子实现列表里的先后顺序决定。如果不看源码你根本不知道这个顺序是怎么来的只能靠试。第二个问题更典型。我想在pytest_terminal_summary里追加内容但这个钩子不是一个先来后到覆盖的机制而是所有注册过的实现都会被依次调用返回值通常没人接。第三方插件如果先执行并且自己做了终端输出我的追加内容就排到后面视觉上感觉被截断了。这不是bug这是插件系统的工作方式。这两个场景指向的源码位置非常集中插件发现逻辑在_pytest/config/__init__.py的PytestPluginManager里配合pluggy的load_setuptools_entrypoints。插件注册的核心在pluggy/manager.py的PluginManager.register。钩子执行顺序在pluggy/hookcaller.py和pluggy/_callers.py里由_multicall负责逐一调用。1.2 三层结构pytest、pluggy、打包系统各管一段先说一个重要认知pytest的插件系统并不是pytest自己从零写的核心是一个叫pluggy的库pytest官方团队自己维护的hook插件框架。pytest在这个框架之上定义了业务钩子比如pytest_configure、pytest_runtest_makereport。所以要理清楚一个插件从安装到生效的完整过程其实涉及三层层职责关键代码位置打包系统把插件暴露给pytestpyproject.toml/setup.py里的pytest11entry pointpluggy插件注册、钩子收集、调用调度pluggy/manager.py、pluggy/hookcaller.pypytest定义钩子规范、加载来源策略_pytest/config/__init__.py、_pytest/hookspec.py这三层缺一不可。很多人写插件时只在Python包里定义了一个pytest_configure函数但没写entry_points结果手动-p能加载、安装后不生效就是没搞懂第一层。理清这条主线之后剩下的问题就变成三个具体环节插件从哪来、插件注册时发生了什么、钩子调用时按什么顺序跑。2. 插件发现链路Entry Points、命令行参数和conftest的先后次序2.1 pytest11分组插件与Python打包体系的连接点如果你写过第三方pytest插件肯定在pyproject.toml里见过这么一段[project.entry-points.pytest11] myplugin myplugin.plugin这个pytest11就是pytest留给插件世界的暗号。Python生态里有一套标准的入口点机制简单说就是一个包安装后可以在它的打包元数据里声明我提供哪些可被外部发现的功能入口。pytest约定凡是声明在pytest11分组里的入口都视为pytest插件。pluggy源码里对应的下载逻辑在PluginManager.load_setuptools_entrypoints。它做的事情很直接def load_setuptools_entrypoints(self, group, nameNone): for entry_point in importlib_metadata.entry_points().select(groupgroup): if name is not None and entry_point.name not in name: continue if self.get_plugin(entry_point.name) is not None: continue self._load_plugin_plugin(entry_point)_load_plugin_plugin里会调用entry_point.load()也就是真正import这个插件模块然后以entry point的name作为插件名去注册。注意这里说的name不是模块名不是包名而是myplugin myplugin.plugin里左边的那个标识符。这就是为什么你有时候在pytest --trace-config里看到插件名是html而不是pytest_html因为pytest-html这个包在entry point里注册的name就叫html。再强调一个细节load_setuptools_entrypoints在被调用之前会先检查get_plugin(entry_point.name)是不是已经注册过。如果命令行里已经用-p手动加载了一个同名插件这里会直接跳过避免重复注册。2.2 -p参数、PYTEST_PLUGINS与pytest_plugins的加载时点除了entry point这种全自动发现方式pytest还提供了几个手动入口源头上都集中在PytestPluginManager的consider_*系列方法。-p参数走的是consider_pluginarg。这个方法的实现不复杂关键是处理两种前缀-p myplugin直接调用import_plugin(myplugin)加载并注册。-p no:myplugin调用set_blocked(myplugin)把这个名字设为封禁状态后续任何来源想注册同名插件都会被忽略。PYTEST_PLUGINS环境变量走的是consider_env变量里用逗号分隔多个插件名按顺序逐个import_plugin。这个机制在CI环境里特别有用你不想改配置文件但想临时挂一个私有插件设个环境变量就行。还有一个容易被忽略的入口conftest.py里的pytest_plugins变量。它定义在根conftest里时可以指定要加载的外部插件模块比如pytest_plugins [myplugin, pytest_mock]需要明确的是非根目录conftest里直接写pytest_plugins会抛错这是pytest故意做的限制目的是避免不同目录下的conftest各自为政让加载链路变得不可预测。2.3 加载顺序的源码依据和trace确认整理一下不同来源的加载顺序我用一个表格把它固化下来加载来源触发点典型时机注册名示例内置插件addhooks、pluginmanager.register启动早期cacheprovider、terminal-p参数consider_pluginarg处理命令行时你指定的模块名PYTEST_PLUGINS环境变量consider_env处理命令行时逗号分隔列表pytest11entry pointsload_setuptools_entrypoints环境变量之后html、xdistconftest.pyconsider_conftestrootdir确定后文件路径名pytest_plugins变量加载根conftest时conftest加载中指定模块名这里有个很反直觉的点conftest里的钩子通常比entry point插件晚注册。因为conftest必须等到rootdir确定之后才能找到并加载而第三方插件在命令行解析阶段就被注册了。反应到执行顺序上默认情况下第三方插件的pytest_collection_modifyitems往往排在conftest里同名钩子的前面。怎么验证用pytest --trace-config跑一次。这个内置参数会打印所有插件加载的日志包括每个entry point何时import、每个conftest何时加载。我强烈建议你在怀疑插件顺序时先跑这个命令很多疑惑会当场解决。3. PluginManager注册流程插件身份、名字冲突与旧式约定3.1 PytestPluginManager在基类之上加了什么pytest自己的插件管理器长这样位置在_pytest/config/__init__.pyclass PytestPluginManager(PluginManager[HookspecMarker]): def __init__(self) - None: super().__init__(pytest) self._conftest_plugins set() ...它继承了pluggy.PluginManager构造函数里把项目的标识名设成了pytest。这个标识名直接决定了后面hook标记的匹配规则只有被HookspecMarker(pytest)和HookimplMarker(pytest)标记过的函数才会被这个管理器识别。PytestPluginManager在基类之上主要加了conftest相关的缓存、-p参数处理、环境变量处理、entry point批量加载等pytest特意扩展的能力。所以你在阅读源码时核心的注册、钩子收集逻辑其实都在pluggy里pytest只是在外面包了一层业务逻辑。3.2 register方法到底在做什么很多新手以为注册插件就是把模块对象往一个列表里塞。实际上register这个方法做的事比想象中多得多。pluggy.PluginManager.register(plugin, nameNone)的核心逻辑可以拆成四步决定插件名。如果没传name会尝试从模块的__name__推导如果推导不出来用变量名。检查是否被blocked。如果这个插件名已经在封禁名单里直接返回None这里对应-p no:的禁用逻辑。遍历插件模块的dir(plugin)找出所有被识别为hookimpl的函数。对每个hookimpl找到它对应的HookCaller然后add_impl把实现加进去。第3步是关键。它用dir()去扫插件模块里所有属性然后调用parse_hookimpl_opts判断某个函数算不算hookimpl。如果是就包装成一个HookImpl对象挂到对应的钩子上。这带来一个结果只要一个函数满足识别规则不管它叫什么名字都可能被当成hook实现收集。这也解释了为什么插件里随意定义一个普通函数会有风险。3.3 parse_hookimpl_opts的pytest前缀兼容逻辑这里有一个很值得说的细节。你在conftest里经常这样写def pytest_configure(config): pass这个函数没有加任何pytest.hookimpl装饰器但它确实被当成hook实现收集了。为什么因为PytestPluginManager重写了parse_hookimpl_opts。它的逻辑大致是如果函数名以pytest_开头并且后面不是大写字母避免误伤pytest_模块内部的私有方法就默认当成hookimpl收集如果名称不满足这个前缀条件才回退到基类逻辑去检查函数上有没有被pytest_impl标记。这意味着pytest向后兼容了老式命名约定只要你的函数名带pytest_前缀即使不装饰也能生效。但这是把双刃剑。我见过有人在一个插件模块里写了个pytest_helper()普通工具函数结果被当成hookimpl收集导致每次运行都触发一个参数不匹配的warning。为了避免这种坑我的建议是新代码一律显式加pytest.hookimpl装饰器不要再依赖前缀约定。3.4 blocked机制为什么重复注册会被拦截前面提到set_blocked这里展开说一下。PytestPluginManager在consider_pluginarg里处理-p no:xxx时会调用pluginmanager.set_blocked(xxx)。之后任何来源尝试注册名为xxx的插件都直接跳过。这个机制对调试非常有用。比如你想完全禁用pytest内置的缓存插件可以这样pytest -p no:cacheprovider有时第三方插件之间互相依赖A插件依赖B插件但B插件的入口点名字和另一个包冲突了用-p no:xxx可以精确地把那个冲突的插件禁掉。注意这里的名字是entry point的name不是模块名。4. hookspec与hookimpl约定之上还有一层显式契约4.1 HookspecMarker把规范函数写在明处pytest在_pytest/hookspec.py里定义了几乎所有的内置钩子规范。这个文件的开头通常是这样from pluggy import HookspecMarker hookspec HookspecMarker(pytest) hookspec def pytest_addoption(parser, pluginmanager): ...HookspecMarker(pytest)这个装饰器做的事情本质上是给被装饰的函数打上一个私有属性标记它是属于pytest项目的hook规范。之后PluginManager.add_hookspecs会读取这些规范函数逐个生成对应的HookCaller对象。所以hookspec回答的问题是pytest世界里存在哪些钩子每个钩子应该传什么参数。hookimpl实现的函数必须和这些规范兼容pluggy在注册时会做参数检查参数对不上会直接抛错。4.2 HookimplMarker标记一个可被收集的实现对应的HookimplMarker是给插件实现方用的from pluggy import HookimplMarker hookimpl HookimplMarker(pytest) hookimpl def pytest_configure(config): ...hookimpl装饰器实际上也没有魔法它就是往函数对象上加一个_pytest_impl属性里面存着tryfirst、trylast、hookwrapper、optionalhook这些选项。真正收集发生在register时。pluggy通过parse_hookimpl_opts读到函数上的这个属性如果属性存在就把这个函数包装成HookImpl并关联到对应名称的HookCaller上。这里必须提醒一个重要的点hookimpl对应的函数名必须和hookspec里的规范函数名完全一致。装饰器只会标记这是个hook实现不会帮你自动改名。你写了个hookimpl def my_own_config(config)它不会去代替pytest_configure而是尝试寻找名为my_own_config的hook规范找不到就新建一个没人调的孤立HookCaller。4.3 一次HookCaller调用背后发生了什么当pytest内部执行某个钩子时比如执行pytest_runtest_makereport它本质上是在调用一个HookCaller对象。这个对象持有一个实现列表调用时的核心逻辑在_multicall函数里。大致流程是把普通实现和wrapper实现分开。按排序后的顺序依次调用普通实现。wrapper实现包裹在外层通过yield控制前后时机。如果有firstresultTrue的规范第一个返回非None结果的实现会提前终止后续调用。值得一提的是普通hook实现的返回值默认没人接收。pytest_configure返回什么pytest通常不关心pytest_runtest_makereport的返回结果会被收集是因为这个钩子本身被定义为firstresultTrue并有特殊处理。这个约定很反直觉很多人以为可以在pytest_configure里return一个值传到下一个钩子实际上不行。想要跨钩子传状态正确做法是挂到config对象或者自定义的类实例上。4.4 optionalhook声明没有配置也不会炸插件开发里还有一个容易被忽视的参数pytest.hookimpl(optionalhookTrue)。它的含义是这个hook实现是可选性的即使对应的hookspec在pytest当前版本里不存在也不要报错。为什么需要它因为pytest版本迭代会增删钩子。你的插件可能想在旧版pytest上也跑但你用了新版才有的钩子名。如果不加optionalhookTruepluggy在注册时会因为找不到对应hookspec直接抛ValueError。加了它之后注册阶段就不会因为找不到规范而崩溃。这个参数我在做跨版本兼容的插件时几乎必用。5. 钩子执行顺序tryfirst、trylast、wrapper与覆盖内置钩子5.1 排序器如何处理注册顺序和特殊标记前面说过多插件监听同一个钩子时执行顺序非常重要。那pluggy到底怎么排序源码里有个专门的函数处理这件事它遵循几条主规则带tryfirstTrue的实现排在普通实现前面。带trylastTrue的实现排在普通实现后面。同一档内按注册顺序排列。wrapper实现整体排在普通实现之后因为wrapper要包裹整段调用链。所以默认情况下注册越早钩子执行越靠前。这个注册顺序就是第三节里说的加载顺序决定的内置插件最早-p和PYTEST_PLUGINS次之pytest11entry point再往后conftest最后。这意味着如果你在conftest里写了个pytest_collection_modifyitems有个第三方插件也写了同名实现那么默认第三方插件先生效你的后执行。如果你想强制自己的实现排在第三方前面可以在装饰器里加tryfirstTrue如果只是想尽量最后一个收尾处理用trylastTrue。5.2 覆盖内置钩子不生效是最常见误区回到文章开头那个场景。很多人想覆盖pytest内置钩子于是在自己的插件里写了同名实现并且期待它取代内置实现。但hook系统不是覆盖关系它是追加关系。内置插件注册得更早你的实现注册得更晚所以内置实现总会先执行。比如你想完全接管pytest_runtest_call自己决定用例怎么跑。如果你只是写一个同名实现内置实现会先执行你的再执行等于跑了两遍。此时正确思路是用-p no:xxx禁掉某个内置插件或把内置插件的实现逻辑在你的实现里主动绕开或用hookwrapper包一层在yield之前拦截在yield之后收尾。大多数情况下hookwrapper是更优雅的方案。5.3 wrapper在钩子前后同时插入动作hookwrapperTrue是一个特殊模式。普通hook实现只在这个钩子被调用时执行一次而wrapper可以同时拿到调用前和调用后两个时机hookimpl(hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield # 这里能拿到完整的调用结果 report outcome.get_result() ...yield之前的代码在所有普通实现之前执行yield之后的代码在所有普通实现完成之后执行。outcome对象可以拿到内部实现的结果也可以对结果做修改。这个机制非常像是给整段调用链套了一层洋葱皮。有个很实用的场景你想在所有用例执行完后统计信息不是等pytest_terminal_summary而是在pytest_runtest_protocol外面包一层wrapper统计每个用例的进出时间。我用过不止一次。5.4 firstresult谁先返回非None谁说了算还有一类特殊钩子定义时带有firstresultTrue含义是一旦某个实现返回了非None结果就停止调用后续实现把这个结果作为整个钩子的返回值。典型例子是pytest_assertrepr_compare用于自定义断言失败的详细输出。多个插件都注册了这个实现但谁先返回一个非None的字符串谁就决定了失败信息长什么样。这类钩子的执行顺序同样重要一旦遇到多个插件都想抢这个输出就得靠tryfirst/trylast和注册顺序来调节。写插件时需要主动区分你要处理的钩子到底是广播型还是firstresult型。广播型只需要关心执行时机firstresult型还需要关心优先级。6. 动手写一个插件并全程跟踪它的加载链路6.1 最简插件骨架与entry_points配置把前面的源码知识合起来落地写一个最小的插件。目录假设是这样myplugin/ ├── pyproject.toml └── src/ └── myplugin/ └── plugin.pypyproject.toml里声明pytest11入口[build-system] requires [setuptools61] build-backend setuptools.build_meta [project] name myplugin version 0.1.0 [project.entry-points.pytest11] myplugin myplugin.plugin插件本体from pluggy import HookimplMarker hookimpl HookimplMarker(pytest) hookimpl(tryfirstTrue) def pytest_configure(config): print(myplugin configure with tryfirst)这里不用pytest_前缀的自动识别而是显式声明hookimpl(tryfirstTrue)保证这个函数即使改名也能被准确收集。6.2 用pytest --trace-config观察加载过程装上插件后执行pytest --trace-config输出里你能看到类似这样的内容PLUGIN registered: module myplugin.plugin from ...这个输出说明entry point已经被找到、导入并注册成功。如果没看到说明你的entry_points分组写错了或者插件没安装到当前Python环境。继续在插件里加一点临时日志也可以用print观察注册顺序。我经常在写插件时先加一个pytest_configure里面打印当前已经注册了哪些插件hookimpl def pytest_configure(config): print(config.pluginmanager.list_name_plugin())list_name_plugin()会返回一份插件名到插件对象的映射。通过它你可以直观看到自己的插件排在什么位置其他插件是什么名字从而推断钩子执行顺序。6.3 三个常见问题与排查思路第一个问题是-p能加载但entry point不生效。排查顺序是先用pip list确认包已安装然后看pyproject.toml里入口分组是不是pytest11再用importlib.metadata.entry_points().select(grouppytest11)在Python交互环境里确认入口存在。这基本能覆盖90%的装了但不生效。第二个问题是插件里定义了pytest_开头的普通函数导致注册警告。定位方法就是在--trace-config日志里搜hookimpl相关的warning。防止再犯统一给所有hook实现加hookimpl普通工具函数改名不要带pytest_前缀。第三个问题是多个插件同名导致后注册的被跳过。这种情况往往发生在两个包都声明了相同的entry point name。处理方式是用-p no:后注册的那个禁用其中一个或者把entry point name改成不冲突的标识。查这个问题的关键命令还是list_name_plugin()一眼就能看出哪个插件名被占用了。最后再分享一点个人体会代码读到这里我最大的感受是pytest插件系统并不神秘它就是一个事件总线加注册表。事件总线是pluggy的hook机制注册表是PluginManager的插件名到插件对象的映射。搞懂了入口点加载、注册扫描、排序调用这三个环节大多数插件相关的怪问题都能自己推断出原因。我后来处理那两个老问题的方式也简单了pytest-ordering和pytest-randomly同时存在时不再试图改代码而是直接确认加载顺序并在自己的conftest里给排序钩子加tryfirst来兜底第二个输出被截断的问题改成在pytest_terminal_summary里用hookwrapper包一层确保收尾内容一定最后输出。两个问题都没改第三方插件只改了我自己的加载方式和装饰器参数。如果你刚开始读这部分源码我建议从pluggy/manager.py的register方法和pluggy/hookcaller.py的_multicall看起这两个函数看明白了其他都是细节。把pytest当黑盒用十年不如花一个下午把它插件系统的核心路径读一遍值。
pytest插件系统源码解析：插件发现、注册与钩子执行顺序
说实话我开始认真读pytest源码并不是因为好奇而是被两个实际问题逼的。第一个问题同事在项目里同时装了pytest-ordering和pytest-randomly结果排序完全失效测试用例顺序跟随机数生成器似的怎么都调不回来。第二个问题我写了一个插件想在pytest_terminal_summary里追加一份自检报告但输出内容总被另一个第三方插件提前截断少了一截。这俩问题表面上叫插件冲突、插件不生效但追到根上全落在pytest插件系统同一段机制里插件是被谁发现的、以什么名字注册的、钩子实现按什么顺序执行。换句话说只要把源码走一遍这类问题基本都能自己定位不用再去翻issue和stackoverflow碰运气。这篇文章不是教你怎么写一个插件demo而是顺着pytest的启动链路把插件系统从发现插件到执行钩子的关键源码拆开讲清楚。读完你至少能回答三个问题第三方插件为什么装完就能生效pytest.hookimpl到底在函数上做了什么为什么你写的pytest_collection_modifyitems有时候排在别人后面1. 插件系统的三条主线发现、注册、调用1.1 两个让我抓狂的真实场景以及它们指向的源码位置先回来说那两个问题。pytest-ordering和pytest-randomly同时存在时pytest-randomly默认会对测试顺序做随机化而pytest-ordering想通过pytest.mark.run这类标记来固化顺序。问题在于两个插件都在监听同一个钩子pytest_collection_modifyitems一个要打乱一个要排固定序最后谁生效完全由钩子实现列表里的先后顺序决定。如果不看源码你根本不知道这个顺序是怎么来的只能靠试。第二个问题更典型。我想在pytest_terminal_summary里追加内容但这个钩子不是一个先来后到覆盖的机制而是所有注册过的实现都会被依次调用返回值通常没人接。第三方插件如果先执行并且自己做了终端输出我的追加内容就排到后面视觉上感觉被截断了。这不是bug这是插件系统的工作方式。这两个场景指向的源码位置非常集中插件发现逻辑在_pytest/config/__init__.py的PytestPluginManager里配合pluggy的load_setuptools_entrypoints。插件注册的核心在pluggy/manager.py的PluginManager.register。钩子执行顺序在pluggy/hookcaller.py和pluggy/_callers.py里由_multicall负责逐一调用。1.2 三层结构pytest、pluggy、打包系统各管一段先说一个重要认知pytest的插件系统并不是pytest自己从零写的核心是一个叫pluggy的库pytest官方团队自己维护的hook插件框架。pytest在这个框架之上定义了业务钩子比如pytest_configure、pytest_runtest_makereport。所以要理清楚一个插件从安装到生效的完整过程其实涉及三层层职责关键代码位置打包系统把插件暴露给pytestpyproject.toml/setup.py里的pytest11entry pointpluggy插件注册、钩子收集、调用调度pluggy/manager.py、pluggy/hookcaller.pypytest定义钩子规范、加载来源策略_pytest/config/__init__.py、_pytest/hookspec.py这三层缺一不可。很多人写插件时只在Python包里定义了一个pytest_configure函数但没写entry_points结果手动-p能加载、安装后不生效就是没搞懂第一层。理清这条主线之后剩下的问题就变成三个具体环节插件从哪来、插件注册时发生了什么、钩子调用时按什么顺序跑。2. 插件发现链路Entry Points、命令行参数和conftest的先后次序2.1 pytest11分组插件与Python打包体系的连接点如果你写过第三方pytest插件肯定在pyproject.toml里见过这么一段[project.entry-points.pytest11] myplugin myplugin.plugin这个pytest11就是pytest留给插件世界的暗号。Python生态里有一套标准的入口点机制简单说就是一个包安装后可以在它的打包元数据里声明我提供哪些可被外部发现的功能入口。pytest约定凡是声明在pytest11分组里的入口都视为pytest插件。pluggy源码里对应的下载逻辑在PluginManager.load_setuptools_entrypoints。它做的事情很直接def load_setuptools_entrypoints(self, group, nameNone): for entry_point in importlib_metadata.entry_points().select(groupgroup): if name is not None and entry_point.name not in name: continue if self.get_plugin(entry_point.name) is not None: continue self._load_plugin_plugin(entry_point)_load_plugin_plugin里会调用entry_point.load()也就是真正import这个插件模块然后以entry point的name作为插件名去注册。注意这里说的name不是模块名不是包名而是myplugin myplugin.plugin里左边的那个标识符。这就是为什么你有时候在pytest --trace-config里看到插件名是html而不是pytest_html因为pytest-html这个包在entry point里注册的name就叫html。再强调一个细节load_setuptools_entrypoints在被调用之前会先检查get_plugin(entry_point.name)是不是已经注册过。如果命令行里已经用-p手动加载了一个同名插件这里会直接跳过避免重复注册。2.2 -p参数、PYTEST_PLUGINS与pytest_plugins的加载时点除了entry point这种全自动发现方式pytest还提供了几个手动入口源头上都集中在PytestPluginManager的consider_*系列方法。-p参数走的是consider_pluginarg。这个方法的实现不复杂关键是处理两种前缀-p myplugin直接调用import_plugin(myplugin)加载并注册。-p no:myplugin调用set_blocked(myplugin)把这个名字设为封禁状态后续任何来源想注册同名插件都会被忽略。PYTEST_PLUGINS环境变量走的是consider_env变量里用逗号分隔多个插件名按顺序逐个import_plugin。这个机制在CI环境里特别有用你不想改配置文件但想临时挂一个私有插件设个环境变量就行。还有一个容易被忽略的入口conftest.py里的pytest_plugins变量。它定义在根conftest里时可以指定要加载的外部插件模块比如pytest_plugins [myplugin, pytest_mock]需要明确的是非根目录conftest里直接写pytest_plugins会抛错这是pytest故意做的限制目的是避免不同目录下的conftest各自为政让加载链路变得不可预测。2.3 加载顺序的源码依据和trace确认整理一下不同来源的加载顺序我用一个表格把它固化下来加载来源触发点典型时机注册名示例内置插件addhooks、pluginmanager.register启动早期cacheprovider、terminal-p参数consider_pluginarg处理命令行时你指定的模块名PYTEST_PLUGINS环境变量consider_env处理命令行时逗号分隔列表pytest11entry pointsload_setuptools_entrypoints环境变量之后html、xdistconftest.pyconsider_conftestrootdir确定后文件路径名pytest_plugins变量加载根conftest时conftest加载中指定模块名这里有个很反直觉的点conftest里的钩子通常比entry point插件晚注册。因为conftest必须等到rootdir确定之后才能找到并加载而第三方插件在命令行解析阶段就被注册了。反应到执行顺序上默认情况下第三方插件的pytest_collection_modifyitems往往排在conftest里同名钩子的前面。怎么验证用pytest --trace-config跑一次。这个内置参数会打印所有插件加载的日志包括每个entry point何时import、每个conftest何时加载。我强烈建议你在怀疑插件顺序时先跑这个命令很多疑惑会当场解决。3. PluginManager注册流程插件身份、名字冲突与旧式约定3.1 PytestPluginManager在基类之上加了什么pytest自己的插件管理器长这样位置在_pytest/config/__init__.pyclass PytestPluginManager(PluginManager[HookspecMarker]): def __init__(self) - None: super().__init__(pytest) self._conftest_plugins set() ...它继承了pluggy.PluginManager构造函数里把项目的标识名设成了pytest。这个标识名直接决定了后面hook标记的匹配规则只有被HookspecMarker(pytest)和HookimplMarker(pytest)标记过的函数才会被这个管理器识别。PytestPluginManager在基类之上主要加了conftest相关的缓存、-p参数处理、环境变量处理、entry point批量加载等pytest特意扩展的能力。所以你在阅读源码时核心的注册、钩子收集逻辑其实都在pluggy里pytest只是在外面包了一层业务逻辑。3.2 register方法到底在做什么很多新手以为注册插件就是把模块对象往一个列表里塞。实际上register这个方法做的事比想象中多得多。pluggy.PluginManager.register(plugin, nameNone)的核心逻辑可以拆成四步决定插件名。如果没传name会尝试从模块的__name__推导如果推导不出来用变量名。检查是否被blocked。如果这个插件名已经在封禁名单里直接返回None这里对应-p no:的禁用逻辑。遍历插件模块的dir(plugin)找出所有被识别为hookimpl的函数。对每个hookimpl找到它对应的HookCaller然后add_impl把实现加进去。第3步是关键。它用dir()去扫插件模块里所有属性然后调用parse_hookimpl_opts判断某个函数算不算hookimpl。如果是就包装成一个HookImpl对象挂到对应的钩子上。这带来一个结果只要一个函数满足识别规则不管它叫什么名字都可能被当成hook实现收集。这也解释了为什么插件里随意定义一个普通函数会有风险。3.3 parse_hookimpl_opts的pytest前缀兼容逻辑这里有一个很值得说的细节。你在conftest里经常这样写def pytest_configure(config): pass这个函数没有加任何pytest.hookimpl装饰器但它确实被当成hook实现收集了。为什么因为PytestPluginManager重写了parse_hookimpl_opts。它的逻辑大致是如果函数名以pytest_开头并且后面不是大写字母避免误伤pytest_模块内部的私有方法就默认当成hookimpl收集如果名称不满足这个前缀条件才回退到基类逻辑去检查函数上有没有被pytest_impl标记。这意味着pytest向后兼容了老式命名约定只要你的函数名带pytest_前缀即使不装饰也能生效。但这是把双刃剑。我见过有人在一个插件模块里写了个pytest_helper()普通工具函数结果被当成hookimpl收集导致每次运行都触发一个参数不匹配的warning。为了避免这种坑我的建议是新代码一律显式加pytest.hookimpl装饰器不要再依赖前缀约定。3.4 blocked机制为什么重复注册会被拦截前面提到set_blocked这里展开说一下。PytestPluginManager在consider_pluginarg里处理-p no:xxx时会调用pluginmanager.set_blocked(xxx)。之后任何来源尝试注册名为xxx的插件都直接跳过。这个机制对调试非常有用。比如你想完全禁用pytest内置的缓存插件可以这样pytest -p no:cacheprovider有时第三方插件之间互相依赖A插件依赖B插件但B插件的入口点名字和另一个包冲突了用-p no:xxx可以精确地把那个冲突的插件禁掉。注意这里的名字是entry point的name不是模块名。4. hookspec与hookimpl约定之上还有一层显式契约4.1 HookspecMarker把规范函数写在明处pytest在_pytest/hookspec.py里定义了几乎所有的内置钩子规范。这个文件的开头通常是这样from pluggy import HookspecMarker hookspec HookspecMarker(pytest) hookspec def pytest_addoption(parser, pluginmanager): ...HookspecMarker(pytest)这个装饰器做的事情本质上是给被装饰的函数打上一个私有属性标记它是属于pytest项目的hook规范。之后PluginManager.add_hookspecs会读取这些规范函数逐个生成对应的HookCaller对象。所以hookspec回答的问题是pytest世界里存在哪些钩子每个钩子应该传什么参数。hookimpl实现的函数必须和这些规范兼容pluggy在注册时会做参数检查参数对不上会直接抛错。4.2 HookimplMarker标记一个可被收集的实现对应的HookimplMarker是给插件实现方用的from pluggy import HookimplMarker hookimpl HookimplMarker(pytest) hookimpl def pytest_configure(config): ...hookimpl装饰器实际上也没有魔法它就是往函数对象上加一个_pytest_impl属性里面存着tryfirst、trylast、hookwrapper、optionalhook这些选项。真正收集发生在register时。pluggy通过parse_hookimpl_opts读到函数上的这个属性如果属性存在就把这个函数包装成HookImpl并关联到对应名称的HookCaller上。这里必须提醒一个重要的点hookimpl对应的函数名必须和hookspec里的规范函数名完全一致。装饰器只会标记这是个hook实现不会帮你自动改名。你写了个hookimpl def my_own_config(config)它不会去代替pytest_configure而是尝试寻找名为my_own_config的hook规范找不到就新建一个没人调的孤立HookCaller。4.3 一次HookCaller调用背后发生了什么当pytest内部执行某个钩子时比如执行pytest_runtest_makereport它本质上是在调用一个HookCaller对象。这个对象持有一个实现列表调用时的核心逻辑在_multicall函数里。大致流程是把普通实现和wrapper实现分开。按排序后的顺序依次调用普通实现。wrapper实现包裹在外层通过yield控制前后时机。如果有firstresultTrue的规范第一个返回非None结果的实现会提前终止后续调用。值得一提的是普通hook实现的返回值默认没人接收。pytest_configure返回什么pytest通常不关心pytest_runtest_makereport的返回结果会被收集是因为这个钩子本身被定义为firstresultTrue并有特殊处理。这个约定很反直觉很多人以为可以在pytest_configure里return一个值传到下一个钩子实际上不行。想要跨钩子传状态正确做法是挂到config对象或者自定义的类实例上。4.4 optionalhook声明没有配置也不会炸插件开发里还有一个容易被忽视的参数pytest.hookimpl(optionalhookTrue)。它的含义是这个hook实现是可选性的即使对应的hookspec在pytest当前版本里不存在也不要报错。为什么需要它因为pytest版本迭代会增删钩子。你的插件可能想在旧版pytest上也跑但你用了新版才有的钩子名。如果不加optionalhookTruepluggy在注册时会因为找不到对应hookspec直接抛ValueError。加了它之后注册阶段就不会因为找不到规范而崩溃。这个参数我在做跨版本兼容的插件时几乎必用。5. 钩子执行顺序tryfirst、trylast、wrapper与覆盖内置钩子5.1 排序器如何处理注册顺序和特殊标记前面说过多插件监听同一个钩子时执行顺序非常重要。那pluggy到底怎么排序源码里有个专门的函数处理这件事它遵循几条主规则带tryfirstTrue的实现排在普通实现前面。带trylastTrue的实现排在普通实现后面。同一档内按注册顺序排列。wrapper实现整体排在普通实现之后因为wrapper要包裹整段调用链。所以默认情况下注册越早钩子执行越靠前。这个注册顺序就是第三节里说的加载顺序决定的内置插件最早-p和PYTEST_PLUGINS次之pytest11entry point再往后conftest最后。这意味着如果你在conftest里写了个pytest_collection_modifyitems有个第三方插件也写了同名实现那么默认第三方插件先生效你的后执行。如果你想强制自己的实现排在第三方前面可以在装饰器里加tryfirstTrue如果只是想尽量最后一个收尾处理用trylastTrue。5.2 覆盖内置钩子不生效是最常见误区回到文章开头那个场景。很多人想覆盖pytest内置钩子于是在自己的插件里写了同名实现并且期待它取代内置实现。但hook系统不是覆盖关系它是追加关系。内置插件注册得更早你的实现注册得更晚所以内置实现总会先执行。比如你想完全接管pytest_runtest_call自己决定用例怎么跑。如果你只是写一个同名实现内置实现会先执行你的再执行等于跑了两遍。此时正确思路是用-p no:xxx禁掉某个内置插件或把内置插件的实现逻辑在你的实现里主动绕开或用hookwrapper包一层在yield之前拦截在yield之后收尾。大多数情况下hookwrapper是更优雅的方案。5.3 wrapper在钩子前后同时插入动作hookwrapperTrue是一个特殊模式。普通hook实现只在这个钩子被调用时执行一次而wrapper可以同时拿到调用前和调用后两个时机hookimpl(hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield # 这里能拿到完整的调用结果 report outcome.get_result() ...yield之前的代码在所有普通实现之前执行yield之后的代码在所有普通实现完成之后执行。outcome对象可以拿到内部实现的结果也可以对结果做修改。这个机制非常像是给整段调用链套了一层洋葱皮。有个很实用的场景你想在所有用例执行完后统计信息不是等pytest_terminal_summary而是在pytest_runtest_protocol外面包一层wrapper统计每个用例的进出时间。我用过不止一次。5.4 firstresult谁先返回非None谁说了算还有一类特殊钩子定义时带有firstresultTrue含义是一旦某个实现返回了非None结果就停止调用后续实现把这个结果作为整个钩子的返回值。典型例子是pytest_assertrepr_compare用于自定义断言失败的详细输出。多个插件都注册了这个实现但谁先返回一个非None的字符串谁就决定了失败信息长什么样。这类钩子的执行顺序同样重要一旦遇到多个插件都想抢这个输出就得靠tryfirst/trylast和注册顺序来调节。写插件时需要主动区分你要处理的钩子到底是广播型还是firstresult型。广播型只需要关心执行时机firstresult型还需要关心优先级。6. 动手写一个插件并全程跟踪它的加载链路6.1 最简插件骨架与entry_points配置把前面的源码知识合起来落地写一个最小的插件。目录假设是这样myplugin/ ├── pyproject.toml └── src/ └── myplugin/ └── plugin.pypyproject.toml里声明pytest11入口[build-system] requires [setuptools61] build-backend setuptools.build_meta [project] name myplugin version 0.1.0 [project.entry-points.pytest11] myplugin myplugin.plugin插件本体from pluggy import HookimplMarker hookimpl HookimplMarker(pytest) hookimpl(tryfirstTrue) def pytest_configure(config): print(myplugin configure with tryfirst)这里不用pytest_前缀的自动识别而是显式声明hookimpl(tryfirstTrue)保证这个函数即使改名也能被准确收集。6.2 用pytest --trace-config观察加载过程装上插件后执行pytest --trace-config输出里你能看到类似这样的内容PLUGIN registered: module myplugin.plugin from ...这个输出说明entry point已经被找到、导入并注册成功。如果没看到说明你的entry_points分组写错了或者插件没安装到当前Python环境。继续在插件里加一点临时日志也可以用print观察注册顺序。我经常在写插件时先加一个pytest_configure里面打印当前已经注册了哪些插件hookimpl def pytest_configure(config): print(config.pluginmanager.list_name_plugin())list_name_plugin()会返回一份插件名到插件对象的映射。通过它你可以直观看到自己的插件排在什么位置其他插件是什么名字从而推断钩子执行顺序。6.3 三个常见问题与排查思路第一个问题是-p能加载但entry point不生效。排查顺序是先用pip list确认包已安装然后看pyproject.toml里入口分组是不是pytest11再用importlib.metadata.entry_points().select(grouppytest11)在Python交互环境里确认入口存在。这基本能覆盖90%的装了但不生效。第二个问题是插件里定义了pytest_开头的普通函数导致注册警告。定位方法就是在--trace-config日志里搜hookimpl相关的warning。防止再犯统一给所有hook实现加hookimpl普通工具函数改名不要带pytest_前缀。第三个问题是多个插件同名导致后注册的被跳过。这种情况往往发生在两个包都声明了相同的entry point name。处理方式是用-p no:后注册的那个禁用其中一个或者把entry point name改成不冲突的标识。查这个问题的关键命令还是list_name_plugin()一眼就能看出哪个插件名被占用了。最后再分享一点个人体会代码读到这里我最大的感受是pytest插件系统并不神秘它就是一个事件总线加注册表。事件总线是pluggy的hook机制注册表是PluginManager的插件名到插件对象的映射。搞懂了入口点加载、注册扫描、排序调用这三个环节大多数插件相关的怪问题都能自己推断出原因。我后来处理那两个老问题的方式也简单了pytest-ordering和pytest-randomly同时存在时不再试图改代码而是直接确认加载顺序并在自己的conftest里给排序钩子加tryfirst来兜底第二个输出被截断的问题改成在pytest_terminal_summary里用hookwrapper包一层确保收尾内容一定最后输出。两个问题都没改第三方插件只改了我自己的加载方式和装饰器参数。如果你刚开始读这部分源码我建议从pluggy/manager.py的register方法和pluggy/hookcaller.py的_multicall看起这两个函数看明白了其他都是细节。把pytest当黑盒用十年不如花一个下午把它插件系统的核心路径读一遍值。
