Pytest用的时间长了你一定会遇到一个场景想让测试用例按业务优先级跑、想让超时的用例自动失败、想统计每个用例的耗时和详细失败原因。初期你可能会去改conftest里的fixture或者干脆试着自己包装测试函数结果发现要么控制不了收集阶段要么很难拿到执行结果。这时候你开始意识到Pytest真正强大地方其实是它预留的那套Hook函数机制。Hook让你不需要改Pytest源码也不需要复制粘贴测试执行逻辑只要在conftest.py里或者插件模块里定义同名函数就能在“用例收集”“用例执行”“结果报告”“会话收尾”这些节点上插入自己的代码。换句话说你可以把测试执行过程当成一条流水线hook就是在流水线上装的那些传感器和机械臂装在哪儿、做什么动作由你自己决定。这篇内容适合已经会写test_case、会配fixture、但感觉“测试执行过程像个黑盒”的开发者。我会从hook调用链讲起重点拆几个高价值落地场景用例编排、超时管控、失败重试思路、结果采集与自定义报告最后给一套可以直接参考的全流程管控示例。1. 先搞懂Hook机制Pytest为什么允许你“插手”1.1 pytest的插件架构与hook管线Pytest从设计之初就不是一个“单内核工具”它把几乎所有能力都做成了插件然后通过一个叫pluggy的插件系统把这些能力串联起来。你装的第三方扩展、你写的conftest.py、甚至pytest内置的断言诊断、终端报告本质上都是插件的一部分。这套插件系统的核心是hook。你可以把hook理解成“带协议的事件回调点”pytest在运行过程中会在固定节点广播某个hook名称任何注册了同名函数的插件都能收到通知并按优先级依次执行。普通情况下你不用关心谁是第一个调用者只要定义好函数签名pytest就会在合适时机把你的代码插进去。很多人会把hook和fixture搞混两者的差异其实很清晰fixture解决的是“测试数据怎么准备”属于用例内部依赖hook解决的是“pytest这个框架在收集、执行、报告时怎么运转”属于框架层面控制。fixture管单个用例hook管整场测试流程这才是hook的真正价值。1.2 hook调用链速查从session到testPytest一次完整运行的hook顺序大致如下阶段典型hook实际场景配置阶段pytest_addoption、pytest_configure注册命令行参数、初始化全局数据会话开始pytest_sessionstart连接环境、创建临时目录收集阶段pytest_collectstart、pytest_collection_modifyitems、pytest_collection_finish调整用例顺序、动态标记、按条件过滤执行阶段pytest_runtest_setup、pytest_runtest_call、pytest_runtest_teardown超时控制、失败重试、性能监控报告阶段pytest_runtest_makereport、pytest_runtest_logreport生成单用例结果、同步日志会话收尾pytest_sessionfinish、pytest_terminal_summary写文件、汇总统计、生成自定义报告把这串hook拼起来看就是一条完整的测试生命周期。想控制哪个环节就去监听对应的hook这是理解后面所有示例的前提。1.3 为什么必须用hook而不是“自己改框架”我见过有同事为了统计每个用例的耗时直接去改Pytest的源码后来版本一升级改动全部失效。还有人在测试函数里写start_time和end_time再try/except包一层来做超时控制结果fixture抛异常、test函数装饰器叠加、skip的情况根本管不住。Hook的优势在于它给了一套稳定的“插槽协议”。Pytest的插件规范本身是公开且经过测试的你只依赖协议不依赖具体实现。哪怕Pytest内部逻辑重写只要hook名称和签名还是这些你的代码就不需要跟着改。实际项目里这也是唯一既能深入管控测试过程、又能平滑跟随版本升级的方式。2. 自定义Hook的三种落地方案别再只写conftest.py2.1 conftest.py里的隐藏hook最常见的方式是在conftest.py里直接写hook函数pytest会自动收集当前目录及子目录下的conftest上面定义的hook只作用于这个目录树。比如我想在每次会话开始时打印一行提示def pytest_sessionstart(session): print(开始执行自动化测试准备环境)穿这个就够了你不需要注册、不需要导入pytest运行时会自动发现。conftest.py的优点是“局部生效”适合放在每个测试目录里做独立管控。缺点是作用域经常被搞错你放在tests/api/下的conftest只会影响tests/api/目录里的用例父目录的conftest则对子目录生效。如果你希望一个hook对整场测试的所有用例都生效建议放到项目根目录的conftest.py里并且保证它是pytest搜索路径能覆盖的根位置。2.2 用pytest_plugins引用独立模块当hook逻辑超过几十行时再堆在conftest.py里就会很难读。这时可以抽成一个普通模块比如my_hooks.py# my_hooks.py def pytest_sessionstart(session): print(插件模块里的会话开始钩子)然后在项目根目录的conftest.py里声明pytest_plugins [my_hooks]这样pytest会从当前目录导入my_hooks模块并把它当成一个插件加载。这个方案比把所有逻辑塞进一个文件更清晰也方便你后续把hooks单独拆出去做单元测试。有一点必须提醒pytest_plugins变量只能出现在conftest.py的最顶层不能写在普通测试文件里也不能写在非conftest的模块中否则pytest直接报错。2.3 把hook做成正式插件并全局安装如果你在多个项目里维护同一套测试管控逻辑最专业的是把它做成一个正式的pytest插件通过入口点注册。在pyproject.toml里[project.entry-points.pytest11] my_hooks my_hooks再到你的插件模块里实现hook函数。安装这个包之后所有项目都能自动加载到这套hook不需要每个项目写conftest也不需要手动声明pytest_plugins。这种方式最干净也最接近“测试平台能力沉淀”。代价是插件调试比conftest多一步需要先pip install -e .再跑用例。对于中小项目我用得最多的还是conftest加独立模块足够灵活。还有一点容易被忽略hook函数可以直接用pytest.hookimpl装饰器标记优先级或者行为比如import pytest pytest.hookimpl(tryfirstTrue) def pytest_collection_modifyitems(session, config, items): passtryfirstTrue表示这个实现尽量排在前面执行后面我讲排序和超时的时候这个参数很关键。3. 收集阶段实战用例排序、筛选与动态标记3.1 用pytest_collection_modifyitems实现优先级排序用例多了以后默认按文件里定义顺序跑往往不合适。最常见的需求就是“重要回归用例先跑新功能用例后跑”这属于收集阶段的编排问题fixture解决不了只能在hook里处理。pytest_collection_modifyitems的第三个参数items是一个列表里面是所有待执行的用例节点。你不需要管这些节点怎么收集出来的只要改这个列表pytest后续就会按修改后的顺序执行。假设你已经用marker标记了优先级pytest.mark.priority(P0) def test_login(): pass pytest.mark.priority(P1) def test_add_user(): pass那么在conftest.py里ORDER {P0: 0, P1: 1, P2: 2} def pytest_collection_modifyitems(session, config, items): def _sort_key(item): marker item.get_closest_marker(priority) if marker is None: return (99, item.nodeid) priority marker.args[0] return (ORDER.get(priority, 99), item.nodeid) items[:] sorted(items, key_sort_key)这里很多人会写错成items sorted(...)结果发现排序根本不生效。原因是pytest传递过来的是一个列表引用你重新赋值items只是把局部变量指向了新列表pytest自己手里那个列表还是原样。必须用items[:] ...这种切片复制方式才能真正替换列表内容。3.2 配合pytest_addoption做动态筛选排序还有一个升级玩法让用户通过命令行参数控制跑哪些用例。比如默认跳过所有标记为slow的用例只有在显式传参时才运行。先注册参数def pytest_addoption(parser): parser.addoption(--runslow, actionstore_true, helprun tests marked as slow)再在collect里面做过滤def pytest_collection_modifyitems(session, config, items): if config.getoption(--runslow): return items[:] [item for item in items if not item.get_closest_marker(slow)]别小看这个组合它比你去改测试代码里的大if判断要优雅得多。通过pytest_addoption声明参数再把读取参数的逻辑放在收集阶段整个“跑哪组用例”这件事就和用例本身解耦了。我一般会把冒烟测试、完整回归、慢用例分组做成三个参数日常开发跑冒烟凌晨机器人跑全量这比维护多个测试入口脚本省心太多。3.3 动态标记和临时数据的正确挂法除了排序和过滤收集阶段还可以给用例动态补marker。比如某些用例只有执行时才知道归属模块你可以在收集阶段根据item.nodeid自动加标记def pytest_collection_modifyitems(session, config, items): for item in items: if /api/ in item.nodeid: item.add_marker(api) elif /web/ in item.nodeid: item.add_marker(web)这样之后所有插件都能通过item.get_closest_marker(api)拿到这个分类。还有一种常见需求是把“预计执行时长”或“所属功能模块”挂到用例对象上后续在report里统一读取。可以给item动态挂属性但更规范的是把它写进item.user_propertiesitem.user_properties.append((module, user-center))user_properties最终会出现在pytest生成的report里配合自定义报告导出非常方便。这里有一个经验能用内置机制就别自己造字段否则后面写报告时还得手动拼数据。4. 执行阶段实战超时、重试与链路日志4.1 pytest_runtest_setup / call / teardown到底管什么一个用例在执行阶段会经历三个阶段setup、call、teardown。理解这三者的关系很重要setup执行fixture的setup逻辑、以及unittest风格里的setUp方法。call真正调用测试函数也就是body里的那几行断言逻辑。teardown销毁fixture、执行tearDown方法。Pytest对每个阶段都会生成一个reportreport.when字段区分是哪个阶段。比如用例在fixture里报错那when就是setup而不是call。你在做超时和重试时必须想清楚自己要管哪一个阶段。用hookwrapper的方式包住这些阶段可以同时拿到“执行前”和“执行后”的逻辑import time import pytest pytest.hookimpl(hookwrapperTrue) def pytest_runtest_setup(item): start time.perf_counter() outcome yield cost time.perf_counter() - start print(fSETUP {item.nodeid}: {cost:.3f}s) # 如果想判断setup是否成功需要看 outcome.get_result()很多初学者不清楚yield在这里的含义。hookwrapper里的yield表示“把控制权交给下一个hook实现”yield右边的outcome是一个结果对象通过outcome.get_result()可以拿到最终report。这段代码是理解Pytest内部运行机制的关键我后面会单独讲坑。4.2 用pytest_runtest_call实现超时管控超时管控是执行阶段最有代表性的场景。最简单的实现思路是进入call阶段前设定一个定时器如果用例在指定时间内没有结束就主动抛异常。Unix和Linux下最顺手的是signal.alarm。先在conftest里定义超时异常和handlerimport signal import pytest class _TimeoutExpired(Exception): pass def _timeout_handler(signum, frame): raise _TimeoutExpired(用例执行超时)然后在call阶段挂蛇钩子pytest.hookimpl(hookwrapperTrue) def pytest_runtest_call(item): marker item.get_closest_marker(timeout) timeout marker.args[0] if marker else 0 if timeout 0: yield return old_handler signal.signal(signal.SIGALRM, _timeout_handler) signal.alarm(timeout) try: yield except _TimeoutExpired: pytest.fail(f用例执行超时{timeout}s) finally: signal.alarm(0) signal.signal(signal.SIGALRM, old_handler)这样用例只需要打上pytest.mark.timeout(5)标记执行超过5秒就会被当成失败。有几个细节值得留意signal.alarm(0)必须放在finally里不然一个用例超时后会把定时器留给下一个用例。执行完要恢复旧的signal handler否则你项目里其他代码注册的SIGALRM处理器会被覆盖。这个方案在Windows上不能直接用因为Windows没有SIGALRM。我在公司内部跑定时任务都是从Linux机器上发起的所以影响不大。如果你必须在Windows上做超时可以用多进程或线程Timer但要小心线程安全。4.3 失败用例自动重试为什么这不是一个for循环的事很多人第一个想到的方案是用例失败了我把它重新执行两遍不就行了实际写起来就会发现并不是“调同一个函数两遍”这么简单。pytest全套流程都建立在一次runtest调用上你重复调用测试函数会产生多份report终端会重复打印结果统计插件会计到多次执行如果失败后又重试成功报告里的状态会非常混乱。失败重试是pytest生态里公认最复杂的插件场景之一成熟的第三方插件需要同时接管收集、执行、report几个hook还要处理fixture状态恢复、日志重复、计数归零等问题所以我一直建议如果你不是想研究pytest底层优先评估现成的重试插件别自己造轮子。不过为了让你理解执行阶段的管控粒度这里给一个“函数级重试”的简化思路它只覆盖普通函数测试用例fixture不会重新创建。核心是接管pytest_pyfunc_call这个hook默认实现是调用测试函数本身我们在这里循环调用pytest.hookimpl(hookwrapperTrue) def pytest_pyfunc_call(pyfuncitem): # 这个hook只处理普通函数用例 outcome yield if outcome.get_result().failed: marker pyfuncitem.get_closest_marker(retry) retry_times marker.args[0] if marker else 0 if retry_times: print(f{pyfuncitem.nodeid} 首次执行失败准备重试) ...你看即使只是做“检测到失败”这一步hookwrapper返回后就已经生成了report。要让重试不污染报告必须在上游把report压制掉这就要深入接管pytest_runtest_makereport再配合pytest_runtest_protocol对整个协议做循环。整套实现确实有点复杂这里不展开完整代码。我的建议是小范围内可以使用成熟重试插件但如果你要做二次开发必须先把pytest_runtest_protocol的调用链读明白再动手改。这篇文章的目的一定程度上也是帮你建立这个底层认识。4.4 用hook串起完整链路日志超时和重试属于“介入式管控”还有一个比较务实的需求是“观察式管控”——把每个用例每一步的耗时和状态记录成结构化日志最后汇总。用多个hook各做一件事能拼出整条链路import time import pytest def pytest_runtest_logstart(nodeid, location): print(f开始执行: {nodeid}) pytest.hookimpl(hookwrapperTrue) def pytest_runtest_setup(item): start time.perf_counter() yield item._setup_cost time.perf_counter() - start pytest.hookimpl(hookwrapperTrue) def pytest_runtest_call(item): start time.perf_counter() yield item._call_cost time.perf_counter() - start pytest.hookimpl(hookwrapperTrue) def pytest_runtest_teardown(item): start time.perf_counter() yield item._teardown_cost time.perf_counter() - start我习惯把数据挂在item对象上而不是用全局字典是因为item在同一个用例的各个hook之间天然共享等到pytest_runtest_makereport阶段再统一汇总不需要考虑作用域和并发问题。5. 报告阶段实战把执行结果变成可用数据5.1 pytest_runtest_makereport拿到每个用例的“原厂结果”pytest_runtest_makereport是报告阶段最重要的hook每个setup、call、teardown阶段结束时都会触发一次。它能拿到两部分信息item用例对象和call本次调用对象。基本用法pytest.hookimpl(hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield report outcome.get_result() if report.when call: print(f用例: {item.nodeid}) print(f结果: {report.outcome}) print(f耗时: {report.duration:.3f}s)很多人误以为这里只能拿到失败的原因其实report里面字段很丰富report.outcomepassed、failed、skipped三个基本状态。report.nodeid用例唯一ID。report.duration本阶段耗时。report.longreprtext失败时的堆栈和消息文本。report.caplog用例捕获的日志。report.user_properties你在收集阶段通过item.user_properties存的数据。强烈建议你把收集数据的逻辑放在report.when call分支里因为只有这个分支对应真正的测试函数执行结果。如果放在setup分支里fixture失败时统计口径就脏了。5.2 pytest_terminal_summary从stats里掏出隐藏数据pytest_terminal_summary是在命令行汇总之后回调的hook挂在terminalreporter对象上。这个对象内部有一个stats字典结构大概是stats[passed]、stats[failed]、stats[skipped]、stats[error]、stats[xfailed]、stats[xpassed]等每一项都是report对象列表。在这里可以遍历统计结果做自定义输出def pytest_terminal_summary(terminalreporter, exitstatus, config): stats terminalreporter.stats passed len(stats.get(passed, [])) failed len(stats.get(failed, [])) skipped len(stats.get(skipped, [])) errors len(stats.get(error, [])) print() print( 自定义汇总 ) print(f通过: {passed}, 失败: {failed}, 跳过: {skipped}, 错误: {errors})这个hook特别适合在测试结束的终端上打印一份“一眼看清”的汇总比如失败用例的nodeid清单、耗时Top 5用例、fixture报错数量。需要注意的是exitstatus表示pytest进程的退出码0表示全部通过可以结合你的CI脚本做判断。5.3 自定义JSON报告用sessionfinish把结果落盘如果想让结果被其他系统消费终端打印远远不够。最常见的是生成JSON报告。先在pytest_configure里初始化一个数据容器挂在config上def pytest_configure(config): config._case_results {}然后在makereport收集pytest.hookimpl(hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield report outcome.get_result() if report.when call: config item.config config._case_results[item.nodeid] { result: report.outcome, duration: report.duration, message: report.longreprtext if report.failed else , }最后在pytest_sessionfinish里写文件import json def pytest_sessionfinish(session, exitstatus): with open(report.json, w, encodingutf-8) as fp: json.dump(session.config._case_results, fp, ensure_asciiFalse, indent2)这段代码在大多数项目里直接复制就能用。有一点值得注意我初始化用的字段是config._case_results带下划线前缀意思是我明确知道这是自定义私有字段避免和pytest未来版本新增的属性冲突。你在自己项目里也建议加上前缀不要裸用一个config.results这种很容易撞车的名字。6. 一个全流程管控示例从收集到报告的完整链路6.1 需求设计把前面所有Point串成一个完整示例。模拟项目X里有几类用例希望具备以下管控能力按pytest.mark.priority(P0)标记排序P0先跑P1其次P2最后。支持pytest.mark.timeout(3)做用例级超时超过3秒标记失败。每个用例的最终执行结果和耗时需要记录到JSON文件方便后续统计。终端最后打印一份中文汇总。6.2 完整代码实现目录结构demo_project/ ├── conftest.py └── test_demo.pyconftest.pyimport json import signal import time import pytest PRIORITY_MAP {P0: 0, P1: 1, P2: 2} def pytest_configure(config): config._case_results {} def pytest_collection_modifyitems(session, config, items): def _key(item): marker item.get_closest_marker(priority) priority marker.args[0] if marker else P2 order PRIORITY_MAP.get(priority, 99) return (order, item.nodeid) items[:] sorted(items, key_key) class _TimeoutExpired(Exception): pass def _timeout_handler(signum, frame): raise _TimeoutExpired(用例执行超时) pytest.hookimpl(hookwrapperTrue) def pytest_runtest_call(item): marker item.get_closest_marker(timeout) timeout marker.args[0] if marker else 0 if timeout 0: yield return old_handler signal.signal(signal.SIGALRM, _timeout_handler) signal.alarm(timeout) try: yield except _TimeoutExpired: pytest.fail(f用例执行超时{timeout}s) finally: signal.alarm(0) signal.signal(signal.SIGALRM, old_handler) pytest.hookimpl(hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield report outcome.get_result() if report.when call: item.config._case_results[item.nodeid] { result: report.outcome, duration: round(report.duration, 4), message: report.longreprtext if report.failed else , } def pytest_terminal_summary(terminalreporter, exitstatus, config): stats terminalreporter.stats passed len(stats.get(passed, [])) failed len(stats.get(failed, [])) skipped len(stats.get(skipped, [])) errors len(stats.get(error, [])) print() print( 执行汇总 ) print(f通过: {passed} | 失败: {failed} | 跳过: {skipped} | 错误: {errors}) def pytest_sessionfinish(session, exitstatus): with open(report.json, w, encodingutf-8) as fp: json.dump(session.config._case_results, fp, ensure_asciiFalse, indent2)test_demo.pyimport time import pytest pytest.mark.priority(P1) pytest.mark.timeout(3) def test_first(): time.sleep(0.2) assert True pytest.mark.priority(P0) def test_second(): assert True pytest.mark.priority(P2) def test_slow(): time.sleep(5) assert True6.3 运行效果分析执行pytest -v能观察到test_second先执行因为它的优先级是P0。test_first其次执行P1。test_slow最后执行而且因为sleep 5秒触发超时被标记为failure。终端末尾会打印中文汇总。当前目录生成report.json里面记录每个用例的最终结果和耗时。这个示例看起来简单但它把收集、执行、报告、收尾四个阶段的hook串在了一条链上真正做到了“从收集到报告”的全流程管控。工作中你可以把它当成骨架再往里面扩展自己的业务逻辑比如按模块分组、按文件生成多个报告、对接消息推送等。7. 常见坑与调试技巧读完少走弯路7.1 hook不生效的三个常见原因我在代码评审里最常见到的“hook没反应”基本就是下面几种情况按出现频率排列函数名拼错。比如把pytest_collection_modifyitems写成pytest_collect_modifyitems少了一个“ion”pytest不会报错只会静默不加载。conftest.py位置不对。放在只被部分目录加载的位置却希望它对全量用例生效。函数里写了return把整个hook链打断了。比如在hookwrapper里忘了写yield或者写成了普通return都会导致pytest后续流程直接短路。排查hook是否加载可以用pytest自带的--trace-config参数它能打印出当前加载的所有插件和hook顺序看到自己写的conftest在列表里基本就能排除“没加载”的问题。7.2 hookwrapper的yield语义用hookwrapper时yield不是可有可无而是整个机制的分界线pytest.hookimpl(hookwrapperTrue) def pytest_runtest_call(item): print(执行前) outcome yield print(执行后)yield之前的逻辑在其他实现执行前运行yield之后的逻辑在其他实现执行完后运行outcome.get_result()能拿到之后生成的报告对象。如果你忘了yield后面的实现永远不会执行pytest就会卡住或直接报错。如果你在yield之后不写任何代码那你等于什么都没做完全可以不用hookwrapper。用不用hookwrapper的关键判断是你需要同时操作前置和后置逻辑吗如果只需要在执行前做点事直接定义普通hook函数就够不需要yield。7.3 tryfirst、trylast与hookwrapper的执行顺序差异同一个hook多个实现同时存在时调用顺序受这些参数影响参数对yield前逻辑的影响对yield后逻辑的影响tryfirstTrue尽量早执行反而尽量晚执行trylastTrue尽量晚执行反而尽量早执行hookwrapperTrue本身就会被包一层可插入前后逻辑同上这一点初学者很容易绕晕。记住一句话tryfirst管的是“前面那段代码”的执行顺序yield后面的代码反而因为先进后出的原因最后执行。当多个插件同时Hook同一个事件时优先执行的wrapper最后收尾这是Python生成器协作的经典特征。7.4 一个小技巧先在小项目验证hook再搬到业务里Hook的调试比普通函数麻烦因为它依赖pytest自身的调用时机。我最常用的调试手段是开一个极小的test文件只放一个assert True和assert False的用例然后反复跑通过print输出观察hook触发顺序。确认逻辑没问题后再搬到真实测试工程里。另一个习惯是尽量保持每个hook只做一件事。不要在一个pytest_terminal_summary里又写JSON又写数据库又发通知那样出了问题很难定位。把数据挂到config上、让不同hook分段处理是更可控的做法。我个人在实际项目里的体会是Hook函数最忌讳“一把梭”。你越是想让整个测试流程听话越要拆细收集阶段解决选哪些用例、执行阶段解决怎么限制用例行为、报告阶段解决结果怎么落盘每个环节各司其职这套体系才能真正稳定起来。等你的hook设计足够清晰它带给你的就不只是几个技巧而是对整个测试框架的控制感。 
长河君 · 2026/10/20 8:05:57 · 阅读 1.2k 深入Pytest Hook机制：从用例编排到自定义报告的全流程管控
Pytest用的时间长了你一定会遇到一个场景想让测试用例按业务优先级跑、想让超时的用例自动失败、想统计每个用例的耗时和详细失败原因。初期你可能会去改conftest里的fixture或者干脆试着自己包装测试函数结果发现要么控制不了收集阶段要么很难拿到执行结果。这时候你开始意识到Pytest真正强大地方其实是它预留的那套Hook函数机制。Hook让你不需要改Pytest源码也不需要复制粘贴测试执行逻辑只要在conftest.py里或者插件模块里定义同名函数就能在“用例收集”“用例执行”“结果报告”“会话收尾”这些节点上插入自己的代码。换句话说你可以把测试执行过程当成一条流水线hook就是在流水线上装的那些传感器和机械臂装在哪儿、做什么动作由你自己决定。这篇内容适合已经会写test_case、会配fixture、但感觉“测试执行过程像个黑盒”的开发者。我会从hook调用链讲起重点拆几个高价值落地场景用例编排、超时管控、失败重试思路、结果采集与自定义报告最后给一套可以直接参考的全流程管控示例。1. 先搞懂Hook机制Pytest为什么允许你“插手”1.1 pytest的插件架构与hook管线Pytest从设计之初就不是一个“单内核工具”它把几乎所有能力都做成了插件然后通过一个叫pluggy的插件系统把这些能力串联起来。你装的第三方扩展、你写的conftest.py、甚至pytest内置的断言诊断、终端报告本质上都是插件的一部分。这套插件系统的核心是hook。你可以把hook理解成“带协议的事件回调点”pytest在运行过程中会在固定节点广播某个hook名称任何注册了同名函数的插件都能收到通知并按优先级依次执行。普通情况下你不用关心谁是第一个调用者只要定义好函数签名pytest就会在合适时机把你的代码插进去。很多人会把hook和fixture搞混两者的差异其实很清晰fixture解决的是“测试数据怎么准备”属于用例内部依赖hook解决的是“pytest这个框架在收集、执行、报告时怎么运转”属于框架层面控制。fixture管单个用例hook管整场测试流程这才是hook的真正价值。1.2 hook调用链速查从session到testPytest一次完整运行的hook顺序大致如下阶段典型hook实际场景配置阶段pytest_addoption、pytest_configure注册命令行参数、初始化全局数据会话开始pytest_sessionstart连接环境、创建临时目录收集阶段pytest_collectstart、pytest_collection_modifyitems、pytest_collection_finish调整用例顺序、动态标记、按条件过滤执行阶段pytest_runtest_setup、pytest_runtest_call、pytest_runtest_teardown超时控制、失败重试、性能监控报告阶段pytest_runtest_makereport、pytest_runtest_logreport生成单用例结果、同步日志会话收尾pytest_sessionfinish、pytest_terminal_summary写文件、汇总统计、生成自定义报告把这串hook拼起来看就是一条完整的测试生命周期。想控制哪个环节就去监听对应的hook这是理解后面所有示例的前提。1.3 为什么必须用hook而不是“自己改框架”我见过有同事为了统计每个用例的耗时直接去改Pytest的源码后来版本一升级改动全部失效。还有人在测试函数里写start_time和end_time再try/except包一层来做超时控制结果fixture抛异常、test函数装饰器叠加、skip的情况根本管不住。Hook的优势在于它给了一套稳定的“插槽协议”。Pytest的插件规范本身是公开且经过测试的你只依赖协议不依赖具体实现。哪怕Pytest内部逻辑重写只要hook名称和签名还是这些你的代码就不需要跟着改。实际项目里这也是唯一既能深入管控测试过程、又能平滑跟随版本升级的方式。2. 自定义Hook的三种落地方案别再只写conftest.py2.1 conftest.py里的隐藏hook最常见的方式是在conftest.py里直接写hook函数pytest会自动收集当前目录及子目录下的conftest上面定义的hook只作用于这个目录树。比如我想在每次会话开始时打印一行提示def pytest_sessionstart(session): print(开始执行自动化测试准备环境)穿这个就够了你不需要注册、不需要导入pytest运行时会自动发现。conftest.py的优点是“局部生效”适合放在每个测试目录里做独立管控。缺点是作用域经常被搞错你放在tests/api/下的conftest只会影响tests/api/目录里的用例父目录的conftest则对子目录生效。如果你希望一个hook对整场测试的所有用例都生效建议放到项目根目录的conftest.py里并且保证它是pytest搜索路径能覆盖的根位置。2.2 用pytest_plugins引用独立模块当hook逻辑超过几十行时再堆在conftest.py里就会很难读。这时可以抽成一个普通模块比如my_hooks.py# my_hooks.py def pytest_sessionstart(session): print(插件模块里的会话开始钩子)然后在项目根目录的conftest.py里声明pytest_plugins [my_hooks]这样pytest会从当前目录导入my_hooks模块并把它当成一个插件加载。这个方案比把所有逻辑塞进一个文件更清晰也方便你后续把hooks单独拆出去做单元测试。有一点必须提醒pytest_plugins变量只能出现在conftest.py的最顶层不能写在普通测试文件里也不能写在非conftest的模块中否则pytest直接报错。2.3 把hook做成正式插件并全局安装如果你在多个项目里维护同一套测试管控逻辑最专业的是把它做成一个正式的pytest插件通过入口点注册。在pyproject.toml里[project.entry-points.pytest11] my_hooks my_hooks再到你的插件模块里实现hook函数。安装这个包之后所有项目都能自动加载到这套hook不需要每个项目写conftest也不需要手动声明pytest_plugins。这种方式最干净也最接近“测试平台能力沉淀”。代价是插件调试比conftest多一步需要先pip install -e .再跑用例。对于中小项目我用得最多的还是conftest加独立模块足够灵活。还有一点容易被忽略hook函数可以直接用pytest.hookimpl装饰器标记优先级或者行为比如import pytest pytest.hookimpl(tryfirstTrue) def pytest_collection_modifyitems(session, config, items): passtryfirstTrue表示这个实现尽量排在前面执行后面我讲排序和超时的时候这个参数很关键。3. 收集阶段实战用例排序、筛选与动态标记3.1 用pytest_collection_modifyitems实现优先级排序用例多了以后默认按文件里定义顺序跑往往不合适。最常见的需求就是“重要回归用例先跑新功能用例后跑”这属于收集阶段的编排问题fixture解决不了只能在hook里处理。pytest_collection_modifyitems的第三个参数items是一个列表里面是所有待执行的用例节点。你不需要管这些节点怎么收集出来的只要改这个列表pytest后续就会按修改后的顺序执行。假设你已经用marker标记了优先级pytest.mark.priority(P0) def test_login(): pass pytest.mark.priority(P1) def test_add_user(): pass那么在conftest.py里ORDER {P0: 0, P1: 1, P2: 2} def pytest_collection_modifyitems(session, config, items): def _sort_key(item): marker item.get_closest_marker(priority) if marker is None: return (99, item.nodeid) priority marker.args[0] return (ORDER.get(priority, 99), item.nodeid) items[:] sorted(items, key_sort_key)这里很多人会写错成items sorted(...)结果发现排序根本不生效。原因是pytest传递过来的是一个列表引用你重新赋值items只是把局部变量指向了新列表pytest自己手里那个列表还是原样。必须用items[:] ...这种切片复制方式才能真正替换列表内容。3.2 配合pytest_addoption做动态筛选排序还有一个升级玩法让用户通过命令行参数控制跑哪些用例。比如默认跳过所有标记为slow的用例只有在显式传参时才运行。先注册参数def pytest_addoption(parser): parser.addoption(--runslow, actionstore_true, helprun tests marked as slow)再在collect里面做过滤def pytest_collection_modifyitems(session, config, items): if config.getoption(--runslow): return items[:] [item for item in items if not item.get_closest_marker(slow)]别小看这个组合它比你去改测试代码里的大if判断要优雅得多。通过pytest_addoption声明参数再把读取参数的逻辑放在收集阶段整个“跑哪组用例”这件事就和用例本身解耦了。我一般会把冒烟测试、完整回归、慢用例分组做成三个参数日常开发跑冒烟凌晨机器人跑全量这比维护多个测试入口脚本省心太多。3.3 动态标记和临时数据的正确挂法除了排序和过滤收集阶段还可以给用例动态补marker。比如某些用例只有执行时才知道归属模块你可以在收集阶段根据item.nodeid自动加标记def pytest_collection_modifyitems(session, config, items): for item in items: if /api/ in item.nodeid: item.add_marker(api) elif /web/ in item.nodeid: item.add_marker(web)这样之后所有插件都能通过item.get_closest_marker(api)拿到这个分类。还有一种常见需求是把“预计执行时长”或“所属功能模块”挂到用例对象上后续在report里统一读取。可以给item动态挂属性但更规范的是把它写进item.user_propertiesitem.user_properties.append((module, user-center))user_properties最终会出现在pytest生成的report里配合自定义报告导出非常方便。这里有一个经验能用内置机制就别自己造字段否则后面写报告时还得手动拼数据。4. 执行阶段实战超时、重试与链路日志4.1 pytest_runtest_setup / call / teardown到底管什么一个用例在执行阶段会经历三个阶段setup、call、teardown。理解这三者的关系很重要setup执行fixture的setup逻辑、以及unittest风格里的setUp方法。call真正调用测试函数也就是body里的那几行断言逻辑。teardown销毁fixture、执行tearDown方法。Pytest对每个阶段都会生成一个reportreport.when字段区分是哪个阶段。比如用例在fixture里报错那when就是setup而不是call。你在做超时和重试时必须想清楚自己要管哪一个阶段。用hookwrapper的方式包住这些阶段可以同时拿到“执行前”和“执行后”的逻辑import time import pytest pytest.hookimpl(hookwrapperTrue) def pytest_runtest_setup(item): start time.perf_counter() outcome yield cost time.perf_counter() - start print(fSETUP {item.nodeid}: {cost:.3f}s) # 如果想判断setup是否成功需要看 outcome.get_result()很多初学者不清楚yield在这里的含义。hookwrapper里的yield表示“把控制权交给下一个hook实现”yield右边的outcome是一个结果对象通过outcome.get_result()可以拿到最终report。这段代码是理解Pytest内部运行机制的关键我后面会单独讲坑。4.2 用pytest_runtest_call实现超时管控超时管控是执行阶段最有代表性的场景。最简单的实现思路是进入call阶段前设定一个定时器如果用例在指定时间内没有结束就主动抛异常。Unix和Linux下最顺手的是signal.alarm。先在conftest里定义超时异常和handlerimport signal import pytest class _TimeoutExpired(Exception): pass def _timeout_handler(signum, frame): raise _TimeoutExpired(用例执行超时)然后在call阶段挂蛇钩子pytest.hookimpl(hookwrapperTrue) def pytest_runtest_call(item): marker item.get_closest_marker(timeout) timeout marker.args[0] if marker else 0 if timeout 0: yield return old_handler signal.signal(signal.SIGALRM, _timeout_handler) signal.alarm(timeout) try: yield except _TimeoutExpired: pytest.fail(f用例执行超时{timeout}s) finally: signal.alarm(0) signal.signal(signal.SIGALRM, old_handler)这样用例只需要打上pytest.mark.timeout(5)标记执行超过5秒就会被当成失败。有几个细节值得留意signal.alarm(0)必须放在finally里不然一个用例超时后会把定时器留给下一个用例。执行完要恢复旧的signal handler否则你项目里其他代码注册的SIGALRM处理器会被覆盖。这个方案在Windows上不能直接用因为Windows没有SIGALRM。我在公司内部跑定时任务都是从Linux机器上发起的所以影响不大。如果你必须在Windows上做超时可以用多进程或线程Timer但要小心线程安全。4.3 失败用例自动重试为什么这不是一个for循环的事很多人第一个想到的方案是用例失败了我把它重新执行两遍不就行了实际写起来就会发现并不是“调同一个函数两遍”这么简单。pytest全套流程都建立在一次runtest调用上你重复调用测试函数会产生多份report终端会重复打印结果统计插件会计到多次执行如果失败后又重试成功报告里的状态会非常混乱。失败重试是pytest生态里公认最复杂的插件场景之一成熟的第三方插件需要同时接管收集、执行、report几个hook还要处理fixture状态恢复、日志重复、计数归零等问题所以我一直建议如果你不是想研究pytest底层优先评估现成的重试插件别自己造轮子。不过为了让你理解执行阶段的管控粒度这里给一个“函数级重试”的简化思路它只覆盖普通函数测试用例fixture不会重新创建。核心是接管pytest_pyfunc_call这个hook默认实现是调用测试函数本身我们在这里循环调用pytest.hookimpl(hookwrapperTrue) def pytest_pyfunc_call(pyfuncitem): # 这个hook只处理普通函数用例 outcome yield if outcome.get_result().failed: marker pyfuncitem.get_closest_marker(retry) retry_times marker.args[0] if marker else 0 if retry_times: print(f{pyfuncitem.nodeid} 首次执行失败准备重试) ...你看即使只是做“检测到失败”这一步hookwrapper返回后就已经生成了report。要让重试不污染报告必须在上游把report压制掉这就要深入接管pytest_runtest_makereport再配合pytest_runtest_protocol对整个协议做循环。整套实现确实有点复杂这里不展开完整代码。我的建议是小范围内可以使用成熟重试插件但如果你要做二次开发必须先把pytest_runtest_protocol的调用链读明白再动手改。这篇文章的目的一定程度上也是帮你建立这个底层认识。4.4 用hook串起完整链路日志超时和重试属于“介入式管控”还有一个比较务实的需求是“观察式管控”——把每个用例每一步的耗时和状态记录成结构化日志最后汇总。用多个hook各做一件事能拼出整条链路import time import pytest def pytest_runtest_logstart(nodeid, location): print(f开始执行: {nodeid}) pytest.hookimpl(hookwrapperTrue) def pytest_runtest_setup(item): start time.perf_counter() yield item._setup_cost time.perf_counter() - start pytest.hookimpl(hookwrapperTrue) def pytest_runtest_call(item): start time.perf_counter() yield item._call_cost time.perf_counter() - start pytest.hookimpl(hookwrapperTrue) def pytest_runtest_teardown(item): start time.perf_counter() yield item._teardown_cost time.perf_counter() - start我习惯把数据挂在item对象上而不是用全局字典是因为item在同一个用例的各个hook之间天然共享等到pytest_runtest_makereport阶段再统一汇总不需要考虑作用域和并发问题。5. 报告阶段实战把执行结果变成可用数据5.1 pytest_runtest_makereport拿到每个用例的“原厂结果”pytest_runtest_makereport是报告阶段最重要的hook每个setup、call、teardown阶段结束时都会触发一次。它能拿到两部分信息item用例对象和call本次调用对象。基本用法pytest.hookimpl(hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield report outcome.get_result() if report.when call: print(f用例: {item.nodeid}) print(f结果: {report.outcome}) print(f耗时: {report.duration:.3f}s)很多人误以为这里只能拿到失败的原因其实report里面字段很丰富report.outcomepassed、failed、skipped三个基本状态。report.nodeid用例唯一ID。report.duration本阶段耗时。report.longreprtext失败时的堆栈和消息文本。report.caplog用例捕获的日志。report.user_properties你在收集阶段通过item.user_properties存的数据。强烈建议你把收集数据的逻辑放在report.when call分支里因为只有这个分支对应真正的测试函数执行结果。如果放在setup分支里fixture失败时统计口径就脏了。5.2 pytest_terminal_summary从stats里掏出隐藏数据pytest_terminal_summary是在命令行汇总之后回调的hook挂在terminalreporter对象上。这个对象内部有一个stats字典结构大概是stats[passed]、stats[failed]、stats[skipped]、stats[error]、stats[xfailed]、stats[xpassed]等每一项都是report对象列表。在这里可以遍历统计结果做自定义输出def pytest_terminal_summary(terminalreporter, exitstatus, config): stats terminalreporter.stats passed len(stats.get(passed, [])) failed len(stats.get(failed, [])) skipped len(stats.get(skipped, [])) errors len(stats.get(error, [])) print() print( 自定义汇总 ) print(f通过: {passed}, 失败: {failed}, 跳过: {skipped}, 错误: {errors})这个hook特别适合在测试结束的终端上打印一份“一眼看清”的汇总比如失败用例的nodeid清单、耗时Top 5用例、fixture报错数量。需要注意的是exitstatus表示pytest进程的退出码0表示全部通过可以结合你的CI脚本做判断。5.3 自定义JSON报告用sessionfinish把结果落盘如果想让结果被其他系统消费终端打印远远不够。最常见的是生成JSON报告。先在pytest_configure里初始化一个数据容器挂在config上def pytest_configure(config): config._case_results {}然后在makereport收集pytest.hookimpl(hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield report outcome.get_result() if report.when call: config item.config config._case_results[item.nodeid] { result: report.outcome, duration: report.duration, message: report.longreprtext if report.failed else , }最后在pytest_sessionfinish里写文件import json def pytest_sessionfinish(session, exitstatus): with open(report.json, w, encodingutf-8) as fp: json.dump(session.config._case_results, fp, ensure_asciiFalse, indent2)这段代码在大多数项目里直接复制就能用。有一点值得注意我初始化用的字段是config._case_results带下划线前缀意思是我明确知道这是自定义私有字段避免和pytest未来版本新增的属性冲突。你在自己项目里也建议加上前缀不要裸用一个config.results这种很容易撞车的名字。6. 一个全流程管控示例从收集到报告的完整链路6.1 需求设计把前面所有Point串成一个完整示例。模拟项目X里有几类用例希望具备以下管控能力按pytest.mark.priority(P0)标记排序P0先跑P1其次P2最后。支持pytest.mark.timeout(3)做用例级超时超过3秒标记失败。每个用例的最终执行结果和耗时需要记录到JSON文件方便后续统计。终端最后打印一份中文汇总。6.2 完整代码实现目录结构demo_project/ ├── conftest.py └── test_demo.pyconftest.pyimport json import signal import time import pytest PRIORITY_MAP {P0: 0, P1: 1, P2: 2} def pytest_configure(config): config._case_results {} def pytest_collection_modifyitems(session, config, items): def _key(item): marker item.get_closest_marker(priority) priority marker.args[0] if marker else P2 order PRIORITY_MAP.get(priority, 99) return (order, item.nodeid) items[:] sorted(items, key_key) class _TimeoutExpired(Exception): pass def _timeout_handler(signum, frame): raise _TimeoutExpired(用例执行超时) pytest.hookimpl(hookwrapperTrue) def pytest_runtest_call(item): marker item.get_closest_marker(timeout) timeout marker.args[0] if marker else 0 if timeout 0: yield return old_handler signal.signal(signal.SIGALRM, _timeout_handler) signal.alarm(timeout) try: yield except _TimeoutExpired: pytest.fail(f用例执行超时{timeout}s) finally: signal.alarm(0) signal.signal(signal.SIGALRM, old_handler) pytest.hookimpl(hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield report outcome.get_result() if report.when call: item.config._case_results[item.nodeid] { result: report.outcome, duration: round(report.duration, 4), message: report.longreprtext if report.failed else , } def pytest_terminal_summary(terminalreporter, exitstatus, config): stats terminalreporter.stats passed len(stats.get(passed, [])) failed len(stats.get(failed, [])) skipped len(stats.get(skipped, [])) errors len(stats.get(error, [])) print() print( 执行汇总 ) print(f通过: {passed} | 失败: {failed} | 跳过: {skipped} | 错误: {errors}) def pytest_sessionfinish(session, exitstatus): with open(report.json, w, encodingutf-8) as fp: json.dump(session.config._case_results, fp, ensure_asciiFalse, indent2)test_demo.pyimport time import pytest pytest.mark.priority(P1) pytest.mark.timeout(3) def test_first(): time.sleep(0.2) assert True pytest.mark.priority(P0) def test_second(): assert True pytest.mark.priority(P2) def test_slow(): time.sleep(5) assert True6.3 运行效果分析执行pytest -v能观察到test_second先执行因为它的优先级是P0。test_first其次执行P1。test_slow最后执行而且因为sleep 5秒触发超时被标记为failure。终端末尾会打印中文汇总。当前目录生成report.json里面记录每个用例的最终结果和耗时。这个示例看起来简单但它把收集、执行、报告、收尾四个阶段的hook串在了一条链上真正做到了“从收集到报告”的全流程管控。工作中你可以把它当成骨架再往里面扩展自己的业务逻辑比如按模块分组、按文件生成多个报告、对接消息推送等。7. 常见坑与调试技巧读完少走弯路7.1 hook不生效的三个常见原因我在代码评审里最常见到的“hook没反应”基本就是下面几种情况按出现频率排列函数名拼错。比如把pytest_collection_modifyitems写成pytest_collect_modifyitems少了一个“ion”pytest不会报错只会静默不加载。conftest.py位置不对。放在只被部分目录加载的位置却希望它对全量用例生效。函数里写了return把整个hook链打断了。比如在hookwrapper里忘了写yield或者写成了普通return都会导致pytest后续流程直接短路。排查hook是否加载可以用pytest自带的--trace-config参数它能打印出当前加载的所有插件和hook顺序看到自己写的conftest在列表里基本就能排除“没加载”的问题。7.2 hookwrapper的yield语义用hookwrapper时yield不是可有可无而是整个机制的分界线pytest.hookimpl(hookwrapperTrue) def pytest_runtest_call(item): print(执行前) outcome yield print(执行后)yield之前的逻辑在其他实现执行前运行yield之后的逻辑在其他实现执行完后运行outcome.get_result()能拿到之后生成的报告对象。如果你忘了yield后面的实现永远不会执行pytest就会卡住或直接报错。如果你在yield之后不写任何代码那你等于什么都没做完全可以不用hookwrapper。用不用hookwrapper的关键判断是你需要同时操作前置和后置逻辑吗如果只需要在执行前做点事直接定义普通hook函数就够不需要yield。7.3 tryfirst、trylast与hookwrapper的执行顺序差异同一个hook多个实现同时存在时调用顺序受这些参数影响参数对yield前逻辑的影响对yield后逻辑的影响tryfirstTrue尽量早执行反而尽量晚执行trylastTrue尽量晚执行反而尽量早执行hookwrapperTrue本身就会被包一层可插入前后逻辑同上这一点初学者很容易绕晕。记住一句话tryfirst管的是“前面那段代码”的执行顺序yield后面的代码反而因为先进后出的原因最后执行。当多个插件同时Hook同一个事件时优先执行的wrapper最后收尾这是Python生成器协作的经典特征。7.4 一个小技巧先在小项目验证hook再搬到业务里Hook的调试比普通函数麻烦因为它依赖pytest自身的调用时机。我最常用的调试手段是开一个极小的test文件只放一个assert True和assert False的用例然后反复跑通过print输出观察hook触发顺序。确认逻辑没问题后再搬到真实测试工程里。另一个习惯是尽量保持每个hook只做一件事。不要在一个pytest_terminal_summary里又写JSON又写数据库又发通知那样出了问题很难定位。把数据挂到config上、让不同hook分段处理是更可控的做法。我个人在实际项目里的体会是Hook函数最忌讳“一把梭”。你越是想让整个测试流程听话越要拆细收集阶段解决选哪些用例、执行阶段解决怎么限制用例行为、报告阶段解决结果怎么落盘每个环节各司其职这套体系才能真正稳定起来。等你的hook设计足够清晰它带给你的就不只是几个技巧而是对整个测试框架的控制感。