做测试框架二次开发这些年，我越来越确认一件事：Pytest和unittest真正的分水岭，不在断言写法，也不在fixture组织方式，而在Hook函数。说夸张一点，Pytest的Hook函数机制，是它能从一个“能跑用例的框架”长成“测试平台底座”的核心原因。这篇内容不打算给你抄手册式的API列表，而是沿着标题里那条主线往下走：先搞清楚Hook函数到底在解决什么问题，再把内置的常用Hook逐个拆开看，接着讲怎么自定义属于自己的Hook，最后组合成一套从用例收集、执行到结果输出的全流程管控方案。适合正在做测试平台二次开发、维护公共测试框架、或者被CI质量门禁逼到想骂人的同学。

1. 为什么说Hook是Pytest的“灵魂”：先用两个真实场景建立概念

很多人用Pytest写了一两年用例，对Hook的认知还停留在“conftest.py里写个pytest_开头的函数，好像某个时候会自动执行”。这个理解不算错，但太模糊了。Hook函数真正的价值，是让你在Pytest的运行链路里获得“干预权”。

1.1 场景一：全公司统一的用例标记规范，靠手工维护要崩溃

假设你们测试平台有几百个模块的用例沉淀下来，平台要求每个用例必须带上module、level、owner三类标记，否则后续的统计报表、责任人通知、分级执行全部会错乱。靠什么来保证？人工review代码？不可能的，用例数量一上来，review只能看个大概。

正确的做法是在用例收集完成之后、执行开始之前的那个瞬间插入一段逻辑：遍历所有收集到的测试项，检查标记是否齐全，缺失的直接fail，并给出明确提示。这个“瞬间”就是Hook函数的介入点，具体来说是pytest_collection_modifyitems。有了这道关卡，规范就是代码强制出来的，而不是靠每个人自觉。

1.2 场景二：关键用例失败后，需要拿到完整上下文

再举个例子。你在做接口自动化，一个用例断言失败了，你想第一时间知道失败前最后发出的请求报文、响应报文、当前登录token是否过期。如果你不用Hook，就只能写一堆全局变量，在用例里手动塞上下文，最后在异常处理器里取出来。

而用Hook函数，你可以在用例执行结束后拿到一个report对象，判断到call阶段失败时，主动把当前线程上下文里的请求记录dump到日志文件。业务代码不用动一行，所有用例自动获得这个能力。这就是Hook的“横切”特性，它不是某个用例的功能，而是覆盖整个测试执行链路的公共服务。

1.3 Hook机制的本质：pluggy插件系统链路

Pytest底层的Hook机制并不是自己闭门造车，而是基于一套叫pluggy的插件系统。核心概念就两个：hookspec和hookimpl。

• hookspec是“接口定义”，声明一个Hook叫什么名字、接收什么参数、期望什么返回值。
• hookimpl是“具体实现”，真正写逻辑的地方。

Pytest在运行生命周期里的每个关键节点，都会向pluggy的PluginManager发起一次调用，所有注册过的hookimpl按照一定顺序被执行。conftest.py之所以能自动生效，是因为Pytest会把每个conftest.py文件当作一个插件加载进PluginManager。内置插件、第三方插件、conftest.py里的Hook函数，在pluggy看来都是平等的实现者。

理解这件事非常重要。因为一旦你把Hook当成“某个神秘函数”，你就永远只能在网上抄几个固定的写法。而当你理解了“注册、分发、调用”这条链路，你就能写出自己的Hook，让其他插件、其他conftest.py都来挂载你的扩展点。这也是第三部分要展开的内容。

2. 内置Hook逐个拆解：从收集到报告，Pytest偷偷给了你多少干预点

Pytest内置了几十个Hook，大部分你一辈子都用不上。但有几个是高频中的高频，做全流程管控基本绕不开。我按测试运行的先后顺序来拆。

2.1 pytest_addoption与pytest_configure：规则定在用例执行前

pytest_addoption是给命令行增加自定义参数的入口。它的典型痛点解法是：测试环境切换。与其在脚本里写死环境地址，不如通过参数传进来。

# conftest.py def pytest_addoption(parser): parser.addoption("--env", action="store", default="test", help="运行环境: test/staging/prod") parser.addoption("--retry-count", action="store", type=int, default=0, help="失败用例重试次数")

参数定义好之后，怎么读取？有两种方式，一种是直接用request.config.getoption("--env")，另一种是在pytest_configure里读取一次，存成全局配置，避免每个用例都去解析参数。

def pytest_configure(config): env = config.getoption("--env") config.env_name = env if env == "prod": config.option.strict_markers = True

pytest_configure的执行时机在命令行参数解析完成后、用例收集之前。这里适合做“按启动参数调整全局行为”的逻辑，比如强制开启某个插件、禁止某个标记、初始化全局资源占位等。

2.2 pytest_collection_modifyitems：收集完成后的重排、过滤、依赖调整

这是我认为最值得吃透的内置Hook。它在所有用例收集完毕后、执行开始前触发，给你一个机会直接修改测试项列表。

典型用途有三个：排序、过滤、批量标记。

def pytest_collection_modifyitems(session, config, items): # 1. 按 order 标记排序，没有标记的排最后 items[:] = sorted(items, key=lambda item: ( item.get_closest_marker("order").args[0] if item.get_closest_marker("order") else 9999 )) # 2. 根据命令行参数过滤冒烟用例 if config.getoption("--smoke"): items[:] = [item for item in items if item.get_closest_marker("smoke")]

注意这里一定要用items[:]这样原地切片赋值，直接items = sorted(...)是没用的。这是一个非常经典的坑，因为items是Hook函数收到的列表参数，重新绑定变量不会影响调用方的原始列表。

除了排序过滤，还可以在这里做依赖调整。比如某些用例必须在特定用例之后跑，你可以在收集阶段解析标记，把测试项重新排列。注意，Pytest的用例执行顺序基本等同于items的顺序，所以这个Hook天然就是做全流程顺序编排的核心位置。

2.3 pytest_runtest_setup/call/teardown与makereport：单条用例的四个观察窗

在单个用例执行期间，Pytest提供了非常细颗粒度的Hook。四个关键节点：

• pytest_runtest_setup(item)：用例前置阶段开始前。
• pytest_runtest_call(item)：用例主体逻辑执行前。
• pytest_runtest_teardown(item, nextitem)：用例清理阶段。
• pytest_runtest_makereport(item, call)：每个阶段结束后生成report。

很多人对makereport的理解有偏差，以为它只会在用例失败时触发。实际上，setup、call、teardown三个阶段结束都会调用一次makereport，你可以通过report.when判断当前是哪个阶段。

@pytest.hookimpl(hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield report = outcome.get_result() if report.when == "call" and report.failed: # 拿到失败后的上下文，输出到日志 extra = getattr(item, "_diagnostic_info", None) if extra: report.sections.append(("诊断信息", str(extra)))

hookwrapper=True是这个场景最常用的模式。它相当于一个装饰器，让Hook函数可以分成两段执行：yield之前是前置逻辑，yield之后拿到结果再处理后置逻辑。理解这个模式，你会发现很多“在失败后补一刀”的需求都能用同一套写法解决。

2.4 pytest_terminal_summary与pytest_sessionfinish：把结果交出去

测试执行完了不等于流程结束。你还需要把结果输出给CI系统，写自定义报告，或者更新测试平台的统计数据库。两个Hook值得关注。

pytest_terminal_summary(terminalreporter, exitstatus, config)专门用来向终端追加文本信息。你可以在原有Pytest汇总内容下面追加自定义内容。

def pytest_terminal_summary(terminalreporter, exitstatus, config): terminalreporter.section("自定义汇总") terminalreporter.write_line(f"失败用例数: {len(terminalreporter.stats.get('failed', []))}")

pytest_sessionfinish(session, exitstatus)则在会话真正结束前触发，适合做数据上报、资源清理、生成结构化结果文件。

def pytest_sessionfinish(session, exitstatus): stats = session.config.hook.pytest_report_teststatus() with open("result.json", "w", encoding="utf-8") as f: json.dump({"exitstatus": exitstatus, "passed": len(session.stats.get("passed", []))}, f)

到这里，你已经有能力在Pytest的“收集、执行、汇总”三个阶段分别介入。但这一切仍然是基于内置Hook的覆盖。接下来聊怎么定义自己的Hook，这是很多人没跨过去的一道坎。

3. 手写自定义Hook：从一个用例依赖管理插件说起

自定义Hook这个词容易让人困惑：我自己在conftest.py里写一个pytest_xxx函数算不算自定义Hook？严格说，那是在“实现一个已有的Hook”，不叫“定义Hook”。真正定义自己的Hook，是指你声明了一套新的Hook接口，让别人去实现它。

3.1 先想清楚：你究竟想让别人怎么“挂”你的逻辑

什么时候需要定义自己的Hook？我个人的判断标准很简单：当你发现自己写的插件里，有一段逻辑希望被外部代码扩展，但又不想把自己的内部函数直接暴露给外部调用时，就该定义一个Hook了。

举个例子。假设你在做用例依赖管理，给用例打上了depends标记，执行前需要检查依赖用例是否已经通过。一开始逻辑很简单，你直接在pytest_runtest_setup里判断一下就行。但后来团队要求不同的项目可以自定义“依赖检查策略”，A项目只要看依赖用例的执行状态，B项目还要检查外部服务健康度。这时候你就不该把自己的检查逻辑写死，而应该定义一个扩展点，让不同项目通过自己的conftest.py来覆盖这个检查行为。

3.2 用pytest_addhooks注册自己的hookspec

定义一个自定义Hook，核心是创建带hookspec标记的接口，并注册到Pytest的PluginManager里。

# myplugin/hooks.py import pluggy hookspec = pluggy.HookspecMarker("pytest") hookimpl = pluggy.HookimplMarker("pytest") @hookspec(firstresult=True) def pytest_check_case_dependency(item): """检查用例依赖是否满足。返回True表示满足，False表示阻断。"""

注意这里用的是pluggy.HookspecMarker("pytest")，这表示这个Hook要在Pytest的命名空间下注册。firstresult=True的意思是，多个实现中只要第一个返回非None结果就停止继续调用，适合“只要有一个实现能给出结论就走短路逻辑”的场景。

然后在插件入口里注册：

# myplugin/__init__.py def pytest_addhooks(pluginmanager): from myplugin import hooks pluginmanager.addhooks(hooks)

pytest_addhooks本身也是Pytest内置的Hook，专门用来给PluginManager添加自定义hookspec。这一步做完，Pytest就知道存在一个pytest_check_case_dependency的接口了。

3.3 在自己插件内部和外部conftest中实现这个Hook

接口注册好了，在自己的插件里调用它：

def pytest_runtest_setup(item): dep = item.get_closest_marker("depends") if dep is None: return result = item.config.hook.pytest_check_case_dependency(item=item) if result is False: pytest.skip(f"依赖用例未通过: {dep.args[0]}")

通过item.config.hook对象发起调用，参数必须用关键字形式传入，这是pluggy的硬性要求。

外部团队想要定制这个检查逻辑，只需要在自己的conftest.py里写同名函数：

# 其他项目/conftest.py def pytest_check_case_dependency(item): dep = item.get_closest_marker("depends") if dep: # 自定义检查逻辑 return check_remote_service(dep.args[0]) return True

这样，你的插件框架定义好了规则，具体规则由各个项目自己实现，谁也不需要改别人的代码。这种模式在大型测试团队里非常实用，公共插件负责编排，业务插件负责决策。

3.4 自定义Hook的规范：命名、参数、返回值与覆盖优先级

有几个约定俗成的规范必须守住。

命名一律以pytest_开头，这么做不仅是为了符合Pytest的自动识别机制，更关键的是避免和第三方插件的hook重名。参数全部用关键字形式传递，不要在调用时写item不写参数名。返回值需要在hookspec里明确预期，比如firstresult=True表示短路，或者默认情况下多个返回值会被收集成列表，调用方要自己决定取哪个。

覆盖优先级方面，和内置Hook一样，自定义Hook也遵循pluggy的排序规则。如果你想保证某个实现一定先跑，在实现上加@pytest.hookimpl(tryfirst=True)。这里用pytest.hookimpl装饰器，而不是普通的函数定义，因为普通函数只能作为Pytest已有Hook的实现，而带装饰器才能明确表达排序和wrapper语义。

@pytest.hookimpl(tryfirst=True) def pytest_check_case_dependency(item): ...

4. 从单点介入到全流程管控：把多个Hook串成一套“测试治理方案”

前面都是逐个Hook讲，但真实项目里，Hook从来不是单打独斗。你要做的是把“收集期、执行期、报告期”三个层次的Hook组合起来，形成一套完整的测试治理方案。

4.1 先搭框架：收集期、执行期、报告期各自管什么

这个框架想清楚，后面写代码就不容易乱。

收集期解决“哪些用例跑、以什么顺序跑”的问题，执行期解决“每条用例跑的时候如果有问题怎么应对”的问题，报告期解决“结果如何交出去”的问题。三个阶段的Hook责任明确，互不越界。

4.2 实战：失败自动重试并沉淀诊断上下文

这个场景非常典型。假设接口用例偶发超时，你想给它一次重试机会，但不能无脑重试，重试前必须把上一轮的请求报文、响应报文、耗时都dump下来，方便事后对比。

第一反应是直接用pytest-rerunfailures插件，但如果只是用它，你拿不到“上一次失败时的上下文”。正确做法是结合自己的Hook。

@pytest.hookimpl(hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield report = outcome.get_result() if report.when == "call" and report.failed: if not hasattr(item, "_last_failure_context"): item._last_failure_context = extract_request_context() else: # 第二次失败，把上下文写盘 dump_context(item._last_failure_context, item.name)

然后配合参数控制重试次数：

@pytest.hookimpl(hookwrapper=True) def pytest_runtest_protocol(item, nextitem): retry_count = item.config.getoption("--retry-count", 0) for attempt in range(retry_count + 1): outcome = yield if not outcome.excinfo: break # 失败且未达到最大重试次数，允许继续下一轮 if attempt == retry_count: break

这里用pytest_runtest_protocol做整体包裹，等于把整个用例执行协议都包了一层。注意yield在一个循环里使用时，要理解hookwrapper的语义：每次yield都会触发一次完整的内部协议执行。实际项目里我会更谨慎一点，把这个逻辑拆成“调用期重试”和“运行期诊断”两个Hook组合，避免在protocol层干扰setup/teardown的正常执行。

4.3 实战：按模块维度排序执行，并把关键信息透传到最终报告

另一个常见需求是：用例要按模块维度批量执行，而不是按收集顺序零散执行，同时最终报告里要能看到每个模块的通过率。排序在收集期搞定，统计在报告期搞定。

排序逻辑写在pytest_collection_modifyitems里：

def pytest_collection_modifyitems(session, config, items): def module_sort_key(item): module_name = item.module.__name__ return (module_name, item.name) items[:] = sorted(items, key=module_sort_key)

统计逻辑放在pytest_terminal_summary里面。为了让报告能拿到执行过程中的模块粒度数据，你可以在pytest_runtest_makereport里实时记录每个模块的结果到一个共享对象。

def pytest_runtest_makereport(item, call): if call.when == "call": module = item.module.__name__ key = (module, "passed" if not call.excinfo else "failed") config = item.config config._module_stats = getattr(config, "_module_stats", {}) config._module_stats[key] = config._module_stats.get(key, 0) + 1

然后在报告期读取：

def pytest_terminal_summary(terminalreporter, exitstatus, config): stats = getattr(config, "_module_stats", {}) for (module, status), count in sorted(stats.items()): terminalreporter.write_line(f"{module}: {status} {count}")

这种在configure里挂对象、在makereport里累计、在terminal_summary里消费的模式，是我最常用的跨Hook传数据方式。它比全局变量干净得多，因为数据挂在config对象上，生命周期和测试会话完全一致。

4.4 用Hook做资源生命周期管理，而不是到处写fixture

fixture适合管理单个用例需要的资源，比如临时文件、数据库连接。但有些资源是Session级别的，比如整个测试期间只启动一次的mock服务、只创建一次的测试账号池。这类资源放在fixture里反而别扭，因为每个用例都要声明参数，容易遗漏。

我的做法是在pytest_sessionstart里初始化，在pytest_sessionfinish里释放。

def pytest_sessionstart(session): session._service_pool = ServicePool() session._service_pool.start() session._test_account_pool = AccountPool() def pytest_sessionfinish(session, exitstatus): session._service_pool.stop() session._test_account_pool.release()

这里要注意，资源初始化时如果失败，要在Hook里捕获异常并给出清晰提示，否则整个会话会在用例执行阶段才暴露出初始化问题，排查起来非常痛苦。我通常会在pytest_sessionstart里自己包一层try/except，失败了直接pytest.exit()并附上原因。

5. 落地过程中必须知道的坑：覆盖顺序、插件冲突与排查思路

看再多的Hook理论，不如亲手踩几个坑。这些坑我基本都在真实项目里遇到过。

5.1 同名Hook的执行顺序比你想的更“反直觉”

多个conftest.py或插件同时实现了同一个Hook，执行顺序不是你文件里写的顺序，也不是按字母排序，而是由pluggy的调用规则决定：默认LIFO，也就是后加载的插件先执行。但在不同目录层级下，Pytest加载conftest.py的时机有差异，导致顺序更难预测。

所以，但凡你的逻辑依赖先后顺序，就不要赌隐式顺序，必须用tryfirst=True或trylast=True显式声明。举个例子，你有一个公共插件对用例做了排序，业务conftest.py里也想调整排序，如果两者都实现pytest_collection_modifyitems且都不写优先级，那么业务conftest.py先执行还是后执行，直接决定最终顺序是“业务排序+公共排序”还是“公共排序+业务排序”。

我建议在公共插件里把核心逻辑放在trylast=True上，保证它是最后一道防线，业务侧的调整永远优先于公共侧。这个“公共兜底，业务优先”的思想，比记住LIFO顺序更重要。

5.2 Hook内的异常为什么经常被“吞掉”

Pytest对Hook内部抛出的异常有专门的捕获机制，失败信息会嵌到report对象里，而不是直接在控制台崩溃。所以你经常发现自己写的Hook逻辑有问题，但测试用例还是照常执行，只是report里多了一段traceback。

排查这类问题，最重要的一招是：在你自己写的Hook函数里，不要假设外部一定会捕获异常。调试期可以在Hook函数最外层包一个大try/except，把完整堆栈打印出来，判断到底是Hook本身的问题还是业务代码的问题。

def pytest_runtest_makereport(item, call): try: # 你的Hook逻辑 ... except Exception: import traceback traceback.print_exc() raise

5.3 与xdist、rerunfailures、allure组合时的隐性问题

全流程管控一旦上了规模，必然用到分布式执行、重试、报告美化这些第三方插件。冲突往往不直接体现在报错上，而是体现在行为诡异上。

最典型的是pytest-xdist并行执行时，每个worker进程都是独立的测试会话，你在主进程pytest_sessionfinish里写的资源清理逻辑，并不会在每个worker里都执行。反过来，每个worker的pytest_sessionstart都会初始化自己的服务池，导致服务重复启动。我踩过最深的坑就是在xdist模式下用pytest_sessionstart启动mock服务，结果开了八个端口，连接串了一大片。

xdist下的正确思路是：区分“主进程职责”和“worker进程职责”。收集期的Hook在主进程和worker里都可能触发，但执行期的Hook只在worker里触发。关键统计信息通过resultlog或自定义报告文件汇总，不要在worker里直接写共享文件。

pytest-rerunfailures和pytest_runtest_makereport的交互也要注意。重试插件会在内部自动重新执行用例，你写的makereport逻辑可能会执行多次。如果不希望“失败上下文dump”在第一次失败时就触发，而是重试全部失败后再触发，需要额外判断call.excinfo和重试插件的状态标记。

5.4 三个排查手段：--trace-config、给impl加标识、最小复现

排查Hook问题时，我有三个固定招数。

第一招，pytest --trace-config。这个命令会打印出所有插件和conftest.py的加载顺序，看到顺序你就能对执行顺序有基本判断。

第二招，在自己实现的Hook函数上写一行日志，或者在装饰器上加上@pytest.hookimpl(hookwrapper=True)后的yield前后各打一次。确认这个Hook到底有没有被调用、调用了多少次。

第三招，也是最有效的，造一个最小复现。把问题场景压缩成一个目录：一个conftest.py加一个test_case.py，跑一遍看行为。能在这里稳定复现的，基本就是逻辑问题；在这里复现不了的，多半是插件组合或执行环境的问题。

6. 写在最后：Hook体系的上限取决于你的分层治理意识

做了这么多Pytest的二次开发，我的体会可以用一句话概括：Hook函数不难学，难的是你想清楚每个Hook在整套流程里的定位。

我见过有些团队把几百行业务逻辑塞进一个pytest_collection_modifyitems里，结果测试一跑就卡在收集阶段。也见过另一个团队把Hook按照“收集期规划、执行期诊断、报告期输出”分成三层，每层只负责一件事，代码清晰，扩展也容易。这里面的差别，不是技术能力，而是对测试框架的控制粒度理解。

最后分享一个我一直在用的小技巧：写自定义Hook时，一定要在docstring里写清楚“触发时机、参数含义、返回值约定”，最好再加一个使用示例。因为Hook不是给你一个人用的，像pytest_check_case_dependency这种自定义Hook，团队其他人要用的时候，如果没有清晰注释，他们根本不敢动，最后还是回到各写各的模式，你的全流程管控就白做了。把这层契约维护好，Pytest的Hook体系才能真正成为你测试框架的骨架，而不是一堆散落各处的魔法函数。