ChromeDriver Websocket Connection Error

Problem Statement

When running automated tests with Selenide or Selenium using ChromeDriver, you may encounter a critical connection error:

org.openqa.selenium.remote.http.ConnectionFailedException: 
Unable to establish websocket connection to 
http://localhost:<port>/devtools/browser/<uuid>

This error typically occurs when using ChromeDriver versions 111+ with Selenium versions prior to 4.8.2. The core issue involves a change in Chrome's security model requiring explicit configuration to allow remote origins in your automation setup.

Common symptoms include:

• Tests failing during browser initialization
• Successful test runs only with older Chrome/ChromeDriver versions
• Test suites that previously worked now failing with websocket exceptions

Recommended Solutions

1. Update Selenium to Latest Version (Preferred Solution)

Upgrade to Selenium 4.10.0 or later to resolve compatibility issues with newer Chrome browsers:

<!-- Maven configuration -->
<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.10.0</version>
</dependency>

Key benefits:

• Automatic handling of remote-origin permissions
• Better compatibility with recent Chrome versions
• No code changes required
• Future-proof your test infrastructure

2. Add Remote-Allow-Origins Argument (For Immediate Fix)

If you cannot immediately update Selenium, add a configuration parameter to ChromeOptions:

ChromeOptions options = new ChromeOptions();
options.addArguments("--remote-allow-origins=*");

// For Selenium
WebDriver driver = new ChromeDriver(options);

// For Selenide
Configuration.browserCapabilities = options;

3. Manage Version Compatibility

If updating Selenium isn't feasible, maintain version compatibility:

1. Downgrade Chrome to 105-111 range if test stability is more critical than latest features
2. Use ChromeDriver matching your Chrome version from the ChromeDriver download page
3. Ensure Java 11+ runtime for best compatibility with modern Selenium versions

WARNING

Version pinning is not a long-term solution. Browser security updates may break tests unexpectedly.

Explanation and Technical Context

This error stems from Chrome's security enhancements requiring explicit permission for WebDriver connections. Selenium 4.8.2+ automatically includes the --remote-allow-origins=* argument during initialization, while older versions require manual configuration.

While version 111 of Chrome introduced this requirement, recent Selenium versions have adapted to the new security model. Using the --remote-allow-origins=* flag explicitly enables websocket connections needed for Chrome DevTools Protocol communication.

Common Solutions Comparison

Solution	Difficulty	Stability	Maintenance
Update Selenium	Easy ⭐	High ✅	Low ✅
Remote-allow-origins flag	Medium ⭐⭐	Medium ⚠️	Medium ⚠️
Chrome downgrade	Hard ⭐⭐⭐	Medium ⚠️	High ❌
Java version change	Medium ⭐⭐	Medium ⚠️	Medium ⚠️

Best Practices

1. Keep Selenium dependencies current with version-aware management:

   <!-- Use the latest Selenium compatible with your framework -->
   <properties>
     <selenium.version>4.10.0</selenium.version>
   </properties>

2. Create a centralized WebDriver configuration:

   public WebDriver createDriver() {
       ChromeOptions options = new ChromeOptions();
      
       // Future-proof configuration
       if (isSeleniumOlderThan("4.8.2")) {
           options.addArguments("--remote-allow-origins=*");
       }
      
       return new ChromeDriver(options);
   }

3. Implement cross-version testing in your CI pipeline:

   # Sample test matrix
   stages:
     - test
   jobs:
     chrome115:
       vars: [SELENIUM_VERSION="4.10.0", CHROME_VERSION="latest"]
     chrome112:
       vars: [SELENIUM_VERSION="4.8.3", CHROME_VERSION="112"]

Troubleshooting Additional Issues

If solutions fail, consider these advanced configurations:

// Full ChromeOptions for Edge/Chrome compatibility
EdgeOptions options = new EdgeOptions();
options.setCapability(CapabilityType.ACCEPT_INSECURE_CERTS, true);
options.addArguments("--remote-allow-origins=*");
options.setCapability("ignore-certificate-errors", true);

For JDK HTTP client issues:

// Add to @BeforeSuite configuration
System.setProperty("webdriver.http.factory", "jdk-http-client");

With Maven dependency:

<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-http-jdk-client</artifactId>
    <version>4.10.0</version>
</dependency>

DANGER

Avoid downgrading to Selenium 3.x as recommended in some answers - this introduces security risks and deprecated API usage that will cause more issues long-term.

Conclusion

The websocket connection error occurs due to Chrome security requirements not being met in older Selenium versions. The preferred solution is updating Selenium to v4.8.2+. If immediate updating isn't possible, adding --remote-allow-origins=* to ChromeOptions provides an effective workaround. Always maintain version compatibility between Chrome, ChromeDriver, and Selenium components to prevent test instability.