pytest-xdist 通过多进程并行执行测试绕过 GIL 提升速度,需确保测试无共享状态;安装后用 pytest -n 2 等指定 worker 数,避免 -n auto 在 CI 中误判核数。
pytest-xdist 为什么能提升测试执行速度
它把测试用例自动分发到多个子进程(或远程节点),绕过 Python 的 GIL 限制,真正并行跑测试。不是“看起来快”,是 CPU 核心利用率上去了——前提是你的测试本身不重度串行依赖、不共享状态。
常见错误现象:
,说明没装
;或者跑起来只用了一个进程,大概率是测试文件名/函数名不符合默认匹配规则,导致没找到可分发的用例。
必须安装:
启用并行最简命令:
(自动用满逻辑核)或
(指定 4 个 worker)
不推荐
在 CI 环境用——Docker 容器常报告错误的核数,建议显式写死,比如
每个 worker 是独立 Python 进程,
/
会在每个进程中各执行一次
哪些测试不适合开 -n
一旦测试之间有隐式共享状态(比如共用一个临时数据库、写同一个
下的文件、修改全局变量),并行就会出错——不是报错,而是结果不可预测:A 测试删了表,B 测试正读着,就挂了。
典型使用场景:单元测试、纯计算类测试、HTTP Mock 充分的接口测试。不适合的场景:集成测试里直接连本地 SQLite、用
切工作目录、靠
协调时序。
立即学习
“
Python免费学习笔记(深入)
”;
检查是否安全:先加
跑一遍
,看有没有
、
或断言失败但单跑又通过的情况
临时禁用某模块并行:在测试文件顶部加
不起作用;正确做法是加
注释(注意冒号后空格)
想让某些测试串行执行?用
+ 配合
太重,不如直接拆成两个命令:
worker 初始化和 fixture 隔离怎么做
每个 worker 进程启动时会重新导入测试模块,但不会重新运行 conftest.py 里的 session-scoped fixture——除非你用
且没加
。真要跨 worker 共享资源(比如起一个本地 Redis),得自己管生命周期。
Python 3.14.3
微软官方的 Python 扩展,是 VS Code 安装量最高的扩展(209M+)。集成 IntelliSense(通过 Pylance)、调试(通过 Python Debugger)、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。
下载
最容易被忽略的是日志和输出混杂:
和
在多进程下会乱序、截断,看不出哪条输出属于哪个测试。
确保 fixture 隔离:避免
里返回可变对象(如 dict/list),否则多个 worker 会改同一份内存
worker 启动前执行代码:在 conftest.py 里定义
函数(注意函数名拼写),它会在每个 worker 进程初始化时调用
调试输出乱序?加
(禁用捕获)+
,再配合
看实时流,但别在 CI 里开——输出太难 parse
临时目录隔离:
fixture 本身已按 worker 隔离,但如果你手动用了
,就得自己加进程 ID 后缀,比如
CI 环境中 -n 2 总比 -n 4 快是怎么回事
不是核越多越好。当测试本身 I/O 密集(比如大量读写磁盘、频繁创建进程),增加 worker 反而加剧竞争,尤其是容器里磁盘带宽有限、/tmp 是内存盘但空间小,容易触发 OOM 或超时。
另一个隐蔽原因:某些测试框架(如 Django 的
)内部用了线程锁或信号量,-n 超过一定数量后,worker 会卡在等待锁上,表现就是 CPU 占用低、总耗时不降反升。
查瓶颈:跑
,看 top N 慢的测试是不是集中在某几个文件——可能它们没做并发适配
Docker 里限制资源:用
+
,比不限制但
更稳
GitHub Actions 默认只有 2 核,
就开始抢资源;GitLab CI 的
常是超售的,
是更安全的起点
别信“auto”:在 GitHub Actions Ubuntu runner 上
会返回 12,但实际跑起来经常卡住,硬写
反而快 30%
实际用的时候,核数不是调得越高越好,状态隔离比并行数更重要。很多团队卡在“为什么开了 -n 反而更慢”,问题往往不在 xdist,而在测试自身对并发的假设。
pytest: error: unrecognized arguments: --numprocessespytest-xdistpip install pytest-xdistpytest -n autopytest -n 4-n auto-n 2setup_moduleteardown_moduletmpdiros.chdir()time.sleep()--tb=shortpytest -n 2FileNotFoundErrorOperationalError# pytest.mark.xfail(reason="shared state")# pytest: noxdist@pytest.mark.serial--dist=loadgroup --tx=popen//chdir=.pytest test_serial.py && pytest -n 4 test_fast.pyscope="session"autouse=Trueprint()logging.info()scope="session"pytest_xdist_worker_init--capture=no--log-cli-level=INFOpytest -n 2 -stmpdirtempfile.mkdtemp()mkdtemp(prefix=f"test_{os.getpid()}_")TestCasepytest -n 4 --duration=0--cpus=2-n 2-n 4-n 3shared runners-n 2-n auto-n 2