xdist 是什么
pytest-xdist 是 pytest 的并行执行插件：-n 启动多个 worker 子进程，主进程把用例分发到各 worker 执行，最后汇总结果与统计。直接收益是压缩大型回归套件的墙钟时间；前提是用例互相隔离，否则并行只会把顺序依赖暴露成随机失败。除并行外，--dist 还能控制聚合方式，把同文件、同模块的用例固定到同一 worker，缓解共享资源冲突。
基本信息
| 适用平台 | Python 3.8+，pytest 6/7/8 通用 |
|---|---|
| 安装 | pip install pytest-xdist |
| 关键参数 | -n 进程数（auto 按 CPU 核数），--dist 分发策略 |
| 运行模型 | 每个 worker 为独立进程，内存与夹具状态不共享 |
典型使用场景
- 大型回归套件串行耗时过长，用并行把反馈压回可接受范围
- CI 单机多核环境按核数分配 worker，缩短流水线等待
- 与 -x/--maxfail 组合，快速失败快速反馈
- 用 --dist loadfile/loadscope 把共享夹具的用例聚到同一进程
- 本地提交前用 -n auto 跑全量，替代选择性抽样
常用命令
常用命令
pytest -n auto # 按逻辑 CPU 核数启动 worker
pytest -n 4 --dist loadfile # 4 进程，同文件用例固定在同一个 worker
pytest -n 4 --dist loadscope # 按模块/类聚合，共享模块级夹具
pytest -n auto --dist worksteal # 空闲 worker 窃取队列，缓解长尾（较新版本）
pytest -n 4 -x --maxfail=2 # 并行下尽早中止，保留失败现场
pytest -n 0 # 临时关闭并行，覆盖 addopts 中的设置--dist 策略对照
| 策略 | 行为 | 适用 |
|---|---|---|
| load（默认） | 动态把待执行用例派给空闲 worker | 无聚合需求的常规套件 |
| loadscope | 同一模块或类的用例归同一 worker | 依赖模块级共享夹具 |
| loadfile | 同一文件的用例归同一 worker | 文件内存在共享状态 |
| worksteal | 空闲 worker 从其他队列窃取用例 | 用例耗时差异明显，避免长尾空闲 |
| loadgroup | 按 xdist_group 标记分组 | 需要自定义聚合粒度 |
worker 数不是越大越快：本地 CPU、被测服务与数据库都会成为瓶颈。先取串行基线，再按 2、4、8 梯度找拐点，同时观察被测系统资源。
session 级夹具会在每个 worker 各执行一次：把建库、起容器、写共享文件放进夹具会造成重复执行与资源冲突；共享资源应移到测试外，或按 worker 命名隔离。