如何在GitHub Actions macOS Runner上测试Kivy App？解决OpenGL像素格式创建失败问题

问题背景 #

在GitHub Actions中跨Windows、Linux、macOS测试Kivy应用时，Windows和Linux Runner运行正常，但macOS Runner持续抛出OpenGL相关错误，导致测试失败。

错误日志 #

INFO     kivy:__init__.py:67 Window: Provider: sdl2
CRITICAL kivy:__init__.py:99 Window: Unable to find any valuable Window provider. Please enable debug logging (e.g. add -d if running from the command line, or change the log level in the config) and re-run your app to identify potential causes
sdl2 - RuntimeError: b'Failed creating OpenGL pixel format'
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/kivy/core/__init__.py", line 71, in core_select_lib
    cls = cls()
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/kivy/core/window/window_sdl2.py", line 165, in __init__
    super(WindowSDL, self).__init__()
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/kivy/core/window/__init__.py", line 1129, in __init__
    self.create_window()
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/kivy/core/window/window_sdl2.py", line 316, in create_window
    self.system_size = self._win.setup_window(
  File "kivy/core/window/_window_sdl2.pyx", line 243, in kivy.core.window._window_sdl2._WindowSDL2Storage.setup_window
  File "kivy/core/window/_window_sdl2.pyx", line 76, in kivy.core.window._window_sdl2._WindowSDL2Storage.die

相关代码 #

应用代码（simpleapp.py） #

from kivy.uix.label import Label
from kivy.app import App


class SimpleApp(App):
    def __init__(self, **kwargs):
        super(SimpleApp, self).__init__(**kwargs)
        self.text = "Hello World"

    def build(self):
        return Label(text=self.text)


if __name__ == '__main__':
    SimpleApp().run()

测试代码 #

import unittest
import time
from functools import partial
from kivy.clock import Clock

from simpleapp import SimpleApp


class Test(unittest.TestCase):

    def pause(*args):
        time.sleep(0.000001)

    def run_test(self, app, *args):
        self.assertEqual(app.text, "Hello World")
        app.stop()

    def test_example(self):
        app = SimpleApp()
        p = partial(self.run_test, app)
        Clock.schedule_once(p, 0.000001)
        app.run()


if __name__ == '__main__':
    unittest.main()

GitHub Actions工作流文件 #

name: Python application

on:
  push:
    branches: [ "master" ]
  pull_request:
    branches: [ "master" ]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  mac_test:

    runs-on: macos-latest

    steps:
      - uses: actions/checkout@v4
      - name: Set up Python 3.10
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install kivy pytest
      - name: Test App
        run: |
          python -m pytest

问题原因 #

GitHub的macOS Runner属于无头环境，默认未配置硬件加速的OpenGL支持；而Windows和Linux Runner的虚拟显示环境默认包含必要的图形渲染组件，因此不会触发该错误。

解决办法 #

办法1：指定Kivy使用软件渲染后端 #

通过设置环境变量，让Kivy使用基于软件的OpenGL后端，绕过硬件加速依赖。修改工作流的测试步骤：

- name: Test App
  run: |
    export KIVY_GL_BACKEND=angle_sdl2
    python -m pytest

办法2：配置macOS虚拟显示环境 #

安装XQuartz并启动虚拟显示，模拟图形界面环境：

- name: Install XQuartz and start virtual display
  run: |
    brew install xquartz
    Xvfb :1 -screen 0 1024x768x24 &
    export DISPLAY=:1
- name: Test App
  run: |
    python -m pytest

办法3：修改测试代码启用无头模式 #

在测试代码开头添加Kivy配置，隐藏窗口并禁用实际显示需求：

from kivy.config import Config
# 隐藏窗口
Config.set('graphics', 'window_state', 'hidden')
# 启用伪全屏模式
Config.set('graphics', 'fullscreen', 'fake')
# 禁用多点触控避免额外依赖
Config.set('input', 'mouse', 'mouse,disable_multitouch')

import unittest
import time
from functools import partial
from kivy.clock import Clock

from simpleapp import SimpleApp


class Test(unittest.TestCase):
    # 原有测试代码保持不变

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