Github Actions中执行Selenium测试出现HeadlessException问题求助

问题分析 #

你本地运行无头Chrome测试正常，但Github Actions的Ubuntu runner默认没有X11显示环境，即使启用Chrome无头模式，若测试代码存在依赖AWT图形接口的操作（如java.awt.Robot、Toolkit调用），或Chrome无头参数配置不全，就会触发HeadlessException。

解决方案 #

1. 优化Chrome无头模式参数 #

更新你的ChromeOptions配置，使用新版无头模式并补充必要参数：

case "chrome-headless":
chromeOptions.addArguments("--headless=new"); // 启用新版无头模式，兼容性更强
chromeOptions.addArguments("--no-sandbox"); // 绕过Chrome的沙箱限制，适配CI环境
chromeOptions.addArguments("--disable-dev-shm-usage"); // 解决容器环境中/dev/shm空间不足问题
chromeOptions.addArguments("--window-size=1920,1080"); // 替换start-maximized，无头模式下更可靠
// 新版Chrome无需--disable-gpu参数，可直接移除
WebDriverManager.chromedriver().setup();
return new ChromeDriver(chromeOptions);

2. 在Github Actions中配置虚拟显示（Xvfb） #

在Ubuntu runner上安装并启动Xvfb，模拟X11显示环境：
修改你的Github Actions工作流文件（如.github/workflows/test.yml）：

jobs:
  run-selenium-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 配置JDK环境
        uses: actions/setup-java@v4
        with:
          java-version: '17' # 根据你的项目JDK版本调整
          distribution: 'temurin'
          cache: maven
      - name: 安装Xvfb
        run: sudo apt-get update && sudo apt-get install -y xvfb
      - name: 启动虚拟显示并执行测试
        run: |
          Xvfb :99 -screen 0 1920x1080x24 &
          export DISPLAY=:99
          mvn install -DbrowserType=chrome-headless

3. 检查并移除测试代码中的AWT依赖 #

如果测试代码中使用了java.awt包下的API（如截图、键盘模拟），替换为Selenium原生方法：

• 截图：使用TakesScreenshot接口替代AWT的Robot.createScreenCapture
• 键盘/鼠标操作：使用Selenium的Actions类替代Robot

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