在自动化测试项目中，我们通过
pytest_report_teststatus钩子收集用例结果并上报服务端。本地调试一切正常，可一旦给启动命令加上-n参数（无论是-n 1还是-n 5），同一个用例就会被上报两次——用例明明只执行了一次，服务端却收到两条一模一样的记录。本文从 pytest-xdist 的进程模型入手，剖析 “master + worker 双重触发钩子” 这一根因，给出基于report.worker_id的推荐修复方案与流水线配置建议，并附上服务端幂等兜底思路，帮你绕开这个看似诡异、实则必然的坑。
一、问题背景
本文的问题源于此前两篇系列文章的工作：
- 在 《别再干等测试报告了：用 pytest 钩子实时追上用例执行进度》 中，我们介绍了如何通过
pytest的pytest_report_teststatus钩子来上报用例状态； - 在 《pytest 动态报告：数据可视化篇 —— 用 Golang + Echo 打造自动化测试任务可视化平台》 中，则完整地使用该钩子上报数据，实现了一套动态测试报告功能。
在这套上报机制里，我们通常会在conftest.py中通过pytest_report_teststatus钩子收集每个用例的执行结果，然后上报到服务端：
# conftest.pydefpytest_report_teststatus(report):if(report.when=='setup'andreport.outcome.lower()=='skipped')orreport.when=='call':ifnotUPLOAD_FLAG:return...在继续深入开发新功能的过程中，本地无论是用 PyCharm 直接运行用例，还是执行命令：
pytest-vscases/demo数据都完全正常：每条用例对应一条记录，干净且无重复。
然而一旦进入流水线，并在启动命令中追加并发参数：
pytest-vs-lcases/demo-n1问题立刻出现：同一个用例被上报了两次。
更诡异的是数据规律——-n 5是两次，-n 1也是两次，不多不少，恰好翻倍。这种"稳定地翻倍"通常意味着不是随机竞态，而是有确定性的结构原因。
二、现象
| 启动方式 | 用例执行次数 | 上报次数 |
|---|---|---|
pytest -vs cases/demo | 正常 | 正常 |
pytest -vs cases/demo -n 1 | 正常 | × 2 |
pytest -vs cases/demo -n 5 | 正常 | × 2 |
这里有两个关键观察点：
- 用例本身只执行了一次，pytest 输出里每个用例也只出现一次
PASSED； - 上报次数与并发量无关，
-n 1和-n 5都是两次。
也就是说，重复发生在"上报"这一环，而不是"执行"这一环。
三、原因分析
1.-n会启动 master + worker 两组进程
pytest-xdist的-n参数表示启动并行 worker 的数量。不同启动方式对应的实际进程数如下：
| 命令 | 实际进程 |
|---|---|
不带-n | 只有 1 个主进程 |
-n 1 | master + 1 个 worker（gw0），共 2 个进程 |
-n 5 | master + 5 个 worker（gw0 ~ gw4），共 6 个进程 |
关键点在于：pytest_report_teststatus钩子在 master 和 worker 里各会被调用一次。
- worker 侧：xdist 的 worker 是独立运行的 pytest 进程，它自己执行用例时，也会触发本进程内的
pytest_report_teststatus； - master 侧：master 进程在汇总各 worker 回传的结果时，同样会再次触发这个钩子。
因此，只要开启-n，哪怕只有-n 1，钩子就会在 master 和 gw0 里各执行一次，同一个用例自然被上报两次。
2. 为什么-n 5也是两次，而不是六次？
因为 xdist 默认调度策略下，每个用例只会被分配给一个 worker 执行。worker 只对自己实际执行的用例触发pytest_report_teststatus，而 master 会对所有用例再触发一次。所以：
上报次数 = worker 上报 1 次 + master 上报 1 次 = 2 次这个结果与 worker 数量无关——无论开几个 worker，单个用例的"执行侧上报"始终只有一次，"汇总侧上报"也只有一次。
3. 为什么不带-n就正常？
不带-n时没有 xdist，只有 1 个进程，pytest_report_teststatus只被调用一次，自然不会有重复。
四、解决办法
推荐方案：通过report.worker_id判断当前是否处于 xdist 模式
# conftest.py# 用于修改测试报告的状态（单个用例执行完成后）defpytest_report_teststatus(report):# 输出用例状态（可以进行数据上报）ifnothasattr(report,'worker_id'):# 只有在 pytest 测试命令中使用 -n 参数设置了并发量才会触发上报returnif(report.when=='setup'andreport.outcome.lower()=='skipped')orreport.when=='call':ifnotUPLOAD_FLAG:return...这个写法有两个好处：
- 本地调试不会上报：本地不带
-n运行时，report上没有worker_id属性，hasattr(report, 'worker_id')为False，直接return，不会触发任何上报逻辑，也就不会产生脏数据。 - 流水线才上报：流水线里使用
-n 1或-n N时，report上带有worker_id属性，上报逻辑才会生效。
原理提醒：
report.worker_id是 pytest-xdist 注入的属性，仅存在于 xdist 模式下。它的存在与否，恰好可以作为"当前是否处于并发模式"的判别依据。
流水线配置建议
流水线中可以设置默认并发量为-n 1，同时允许用户自定义：
# 默认值PYTEST_CONCURRENCY=${PYTEST_CONCURRENCY:--n 1}pytest-vs-lcases/demo$PYTEST_CONCURRENCY--alluredir./allure-results这样本地开发时直接执行pytest -vs cases/demo不会上报，只有流水线里才会触发上报逻辑。
兜底方案：服务端加幂等去重
无论客户端怎么控制，网络重试、重复启动、rerun插件都可能导致重复上报。因此建议服务端用唯一键（如pipeline_id + task_id + node_id + 执行序号）做幂等，让重复上报在落库时被吞掉。客户端过滤负责"少发"，服务端幂等负责"万无一失"。
五、常见误区
误区 1：--dist=worksteal能解决重复
不能。--dist只影响用例如何分配给 worker，不影响 “master / worker 都会触发 hook” 这一事实。改变调度策略，重复问题依旧。
误区 2：-n 1等于不带-n
不等。-n 1仍然处于 xdist 模式，会启动 master + gw0 两个进程；只有不带-n才是纯单进程模式。这正是"本地正常、流水线翻倍"的根源所在。
误区 3：在pytest_collection_finish里判断了并发模式就够了
不够。pytest_collection_finish只控制用例清单的上传，而pytest_report_teststatus是另一个钩子，需要单独加判断。两个钩子各管一段，不能混为一谈。
六、总结
| 场景 | 行为 | 是否重复 |
|---|---|---|
不带-n | 单进程，无worker_id | 不上报 |
-n 1 | master + 1 worker，钩子带worker_id | 否，× 1 |
-n N | master + N workers，钩子带worker_id | 否，× 1 |
核心结论：通过hasattr(report, 'worker_id')判断当前是否处于 xdist 并发模式——本地单进程无此属性、直接跳过，流水线并发模式下才执行上报。这样既能避免本地调试时产生脏数据，又能保证流水线里正常上报；同时配合服务端幂等兜底，方能万无一失。
一句话记住这个坑：钩子会在 master 和 worker 两侧各跑一次，
-n一开就翻倍——用worker_id判断自己是否处于并发模式，只在流水线上报，才是正解。
