Selenium WebSocket连接失败

问题描述

在使用 Selenium 或 Selenide 进行自动化测试时，可能会遇到以下错误：

org.openqa.selenium.remote.http.ConnectionFailedException: 
Unable to establish websocket connection to http://localhost:2757/...

该错误表明浏览器无法建立与 Chrome DevTools 的 WebSocket 连接，通常发生在以下环境中：

• Selenium 4.4.0 及以上版本
• Chrome 浏览器 105+
• Linux/Windows/MacOS 系统
• Java 8+

错误根本原因是浏览器安全策略升级。Chrome 从 v111 版本开始增强了跨域安全限制，而旧版 Selenium 没有自动处理该策略变更。

解决方案

方法 1：升级 Selenium 版本（推荐）

这是最彻底的解决方案，无需修改测试代码

从 Selenium 4.8.2 开始，官方已修复此问题，只需升级依赖版本即可：

Maven 配置示例

<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.10.0</version> <!-- 不低于 4.8.2 -->
</dependency>

验证成功版本

以下组合已验证可用：

• Selenium 4.8.2 + Java 11+
• Selenium 4.9.0/4.10.0 + Java 8+

方法 2：添加浏览器启动参数

适合无法立即升级 Selenium 的情况

通过 --remote-allow-origins=* 参数解决跨域限制：

Chrome 示例

ChromeOptions options = new ChromeOptions();
options.addArguments("--remote-allow-origins=*"); // 关键参数
WebDriver driver = new ChromeDriver(options);

Edge 示例

EdgeOptions options = new EdgeOptions();
options.addArguments("--remote-allow-origins=*");
WebDriver driver = new EdgeDriver(options);

安全说明

* 表示允许所有来源，实际生产环境中应限定具体域名：

options.addArguments("--remote-allow-origins=https://yourdomain.com");

方法 3：检查浏览器与驱动版本

Chrome 浏览器与 chromedriver 必须版本匹配。常见错误组合：

• Chrome v114 + chromedriver < 114 ❌
• Chrome v111 + Selenium < 4.8.2 ❌

版本匹配方案

浏览器版本	解决方案
≤ Chrome 110	无需特殊处理
Chrome 111+	升级 Selenium 或添加参数
Chrome ≥114	使用 chromedriver 114+

官方版本对照表

方法 4：切换 HTTP 客户端（备选）

当上述方法无效时，可尝试切换 Selenium 的底层 HTTP 客户端：

// 添加依赖
<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-http-jdk-client</artifactId>
    <version>4.8.1</version>
</dependency>

// 测试启动前设置
System.setProperty("webdriver.http.factory", "jdk-http-client");

原理说明

技术背景

此问题本质是由于 Chrome 加强安全策略：当使用 DevTools 协议时，必须显式声明允许的跨域来源。Selenium 4.4.0~4.8.1 未适配此变更导致连接拒绝。

升级后解决方案对比：

方案	安全系数	维护性	推荐指数
升级 Selenium	★★★★★	★★★★★	⭐⭐⭐⭐⭐
添加启动参数	★★☆☆☆	★★★☆☆	⭐⭐⭐⭐☆
切换 HTTP 客户端	★★★☆☆	★★☆☆☆	⭐⭐⭐☆☆

最佳实践

1. 保持环境更新

   • 使用 Selenium ≥ 4.10.0
   • 定期更新浏览器与驱动

2. 优先在 Selenide 中全局配置

   Configuration.browserCapabilities = new ChromeOptions()
       .addArguments("--remote-allow-origins=http://localhost:8080");

3. CI/CD 环境检查版本兼容性

   # 示例：检查 Chrome 版本
   google-chrome --version
   # 匹配对应 chromedriver
   curl -Lo chromedriver.zip https://chromedriver.storage.googleapis.com/xx.xx.xx/chromedriver_linux64.zip

4. 使用测试基类统一处理

   public class BaseTest {
       @BeforeAll
       static void setup() {
           if(System.getProperty("webdriver.chrome.driver") == null) {
               WebDriverManager.chromedriver().setup();
           }
       }
   }

疑难排查步骤

1. 确认所有依赖版本一致
2. 排查代理/防火墙拦截 localhost 连接
3. 尝试无头模式排除GUI因素：
   options.addArguments("--headless=new")