如何解决PySide6 Qt模块导致GitHub Actions中Tox测试失败的问题

问题根源 #

GitHub Actions的Ubuntu默认runner镜像缺少PySide6加载Qt Widgets所需的系统级图形依赖库（比如libEGL.so.1），且无GUI环境无法满足Qt的显示要求，而本地环境通常已预装这些依赖。

解决方案 #

1. 安装系统级依赖库 #

在GitHub Actions的Workflow文件中，添加安装依赖的步骤，放在安装Python包或执行Tox之前：

- name: Install system dependencies
  run: |
    sudo apt-get update
    sudo apt-get install -y libegl1-mesa libgl1-mesa-glx libxcb-xinerama0 xvfb

这些包包含了Qt所需的EGL、GLX库，以及用于模拟GUI环境的Xvfb工具。

2. 用虚拟显示运行测试 #

因为GitHub Actions环境没有真实显示器，需要用Xvfb模拟GUI环境，有两种实现方式：

• 方式一：在Workflow中包裹Tox命令
  修改Workflow中执行Tox的步骤：

  - name: Run tox tests
    run: xvfb-run tox
  

• 方式二：在tox.ini中配置命令
  在项目的tox.ini里，将测试命令用xvfb-run包裹：

  [testenv]
  commands = xvfb-run python -m pytest tests/  # 替换成你的实际测试命令
  

3. 验证依赖安装 #

如果问题依旧，可以在Workflow中添加步骤检查依赖是否安装成功：

- name: Check installed libraries
  run: |
    ldconfig -p | grep libEGL
    ldconfig -p | grep libGL

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