pytest-xdist分散模式实现远程测试用例执行方法

pytest-xdist 的“远程执行”实为通过 execnet 通道（SSH 或 socket）间接启动远端 worker 进程，并非真正意义上的跨机器调度；其 --ssh 模式因依赖已停更的 execnet，极易因新版 paramiko 不兼容、SSH 配置解析失败、远端 Python 环境缺失或版本不匹配而静默失败或退化为本地运行；相较之下，--tx socket= 模式更可控，但需手动启动远端 socket server、严格同步路径、规避端口冲突，并确保远端具备与本地一致的 Python 版本、完整测试依赖及宽松的安全策略——真正决定成败的，往往不是命令语法，而是 execnet 在远端那一秒无声无息的 worker 启动过程。

pytest-xdist 本身不支持真正的“远程执行”——它只做本地多进程分发，所谓“远程”其实是靠 execnet 的 socket 或 SSH 通道间接实现的。直接跑 pytest -n 4 --ssh 并不会把测试进程真正在远端启动，而是复用 execnet 的通道机制在远端机器上拉起 Python worker 进程。

为什么 --ssh 参数常报错或静默失败

常见现象是命令无报错但测试全在本地跑、stderr 显示 Connection refused、或者卡在 execnet.gateway_bootstrap 阶段。

• pytest-xdist 的 --ssh 依赖已停止维护的 execnet 库，而新版 paramiko（如 3.0+）与之存在兼容问题
• ~/.ssh/config 中若用了 ProxyCommand、Include 或非标准密钥路径（比如 IdentityFile ~/.ssh/id_ed25519），execnet 无法正确解析
• 远端机器必须预装 Python 且可执行 python -c "import execnet"，否则 worker 启动失败，但错误不透出到主进程
• SSH 用户需有免密 sudo 权限（如果测试涉及服务启停等操作），否则 rsync 或 python 调用会因权限被拒中断

--tx socket= 模式比 --ssh 更可控

socket 模式绕过 SSH 密钥和配置复杂度，适合局域网内快速验证，但要注意路径同步和端口冲突。

• 远端先手动运行 python socketserver.py（注意：GitHub 上的原始链接已失效，应使用 https://raw.githubusercontent.com/pytest-dev/execnet/master/execnet/script/socketserver.py）
• 本地执行时必须加 --rsyncdir ./，否则远端 worker 找不到测试文件；若项目含子模块或 src/ 结构，需显式列出所有要同步的目录，例如 --rsyncdir ./ --rsyncdir ./src --rsyncdir ./conftest.py
• 避免硬写 -n 4，改用 -n auto —— execnet 的 socket worker 启动慢，固定数量容易因超时导致部分 worker 未就绪就开跑，造成断连重试
• 端口 8888 若被占用，远端启动时不会报错，但本地 --tx socket=127.0.0.1:8888 会连接失败；建议启动前用 lsof -i :8888 或 netstat -tuln | grep 8888 检查

远端环境必须满足的最小条件

不是“能 SSH 登录就行”，而是 execnet worker 进程实际运行所需的上下文。

• 远端 Python 版本需与本地一致（至少主版本相同），否则 execnet 序列化失败，报错类似 ValueError: unsupported pickle protocol
• 远端需安装 pytest 和所有测试依赖（如 requests、pytest-mock），但 pytest-xdist 本身不用装——worker 只用 execnet 和 pytest core
• --rsyncdir 同步后，远端工作目录是 ./ 下的副本，所以测试中用 os.path.dirname(__file__) 获取路径是安全的；但若用 os.getcwd()，得到的是 execnet 启动时的工作目录（通常是 /tmp 附近），不可靠
• 远端不能启用 SELinux 或 AppArmor 限制 Python 执行网络或临时文件，否则 socket worker 会静默退出

真正麻烦的从来不是命令怎么写，而是 execnet 在远端启动 worker 时那一秒发生了什么——它不打日志、不抛异常、只默默失败。最稳的做法：先在远端手动跑一次 python -c "import execnet; gw = execnet.makegateway('socket=127.0.0.1:8888'); ch = gw.remote_exec('print(1)'); print(ch.receive())"，通了再套 pytest。

理论要掌握，实操不能落！以上关于《pytest-xdist分散模式实现远程测试用例执行方法》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！