使用tox运行PySide6测试时遇qt.qpa.xcb连接失败问题的解决方法

问题分析 #

你遇到的qt.qpa.xcb: could not connect to display错误，核心原因是tox的隔离测试环境没有继承终端的DISPLAY环境变量，同时也未指定Qt使用无显示模式。直接在终端运行测试命令时，环境中存在DISPLAY变量，Qt能正常识别显示设备；但tox默认会隔离环境，且你的passenv配置未包含DISPLAY，导致Qt无法初始化xcb平台插件。

解决方案 #

方案1：传递DISPLAY环境变量给tox环境 #

修改tox配置的passenv部分，添加DISPLAY，让测试环境继承终端的显示变量：

[testenv]
# 其他配置保持不变
passenv =
    HOME
    SETUPTOOLS_*
    PYTHONPATH
    DISPLAY  # 新增该行

方案2：强制Qt使用offscreen无显示平台 #

如果测试不需要真实显示（比如CI环境或无桌面场景），直接在tox环境变量中指定Qt使用offscreen插件，无需依赖DISPLAY：

[testenv]
# 其他配置保持不变
setenv =
    TOXINIDIR = {toxinidir}
    QT_QPA_PLATFORM=offscreen  # 新增该行

方案3：使用xvfb虚拟显示（需真实窗口上下文时） #

若测试需要真实的窗口渲染上下文，可安装xvfb虚拟显示服务，让测试在虚拟桌面中运行：

1. 安装xvfb：

sudo apt install xvfb

2. 修改tox的commands，用xvfb-run包裹测试命令：

[testenv]
# 其他配置保持不变
commands =
    xvfb-run coverage run --context={envname} -m pytest --strict-markers --strict-config --tb=short --verbose --capture=no --full-trace

验证 #

修改配置后重新运行tox，测试应能正常启动Qt应用。

内容的提问来源于stack exchange，提问作者Julian_Orteil