Using Chrome to Fix the DevToolsActivePort File Error in Selenium on GitHub Actions

Overcoming Chrome Test Failures in CI/CD Pipelines

Running Selenium tests in headless Chrome on GitHub Actions should be seamless. Yet, many developers face the frustrating "DevToolsActivePort file doesn’t exist" error. This happens when Chrome, for one reason or another, fails to start properly in the CI environment.

The error message usually signals that Chrome is unexpectedly crashing, which is often a result of mismatched Chrome and ChromeDriver versions or misconfigured options in the test setup. Like many developers, I’ve encountered this challenge, particularly when deploying automated tests in a continuous integration environment.

In this setup, the tiniest misalignment, like a ChromeDriver version mismatch, can bring test execution to a halt, costing valuable time and resources. Fortunately, understanding the underlying issues makes resolving it much easier 🛠️.

In this guide, we’ll dive into the practical steps to prevent and troubleshoot this common error. From Chrome installation specifics to proper driver initialization, you'll find a step-by-step process to ensure smooth test runs every time. Let’s tackle this issue and get your tests back on track!

Detailed Solution for Chrome and ChromeDriver Setup in CI

The scripts above are designed to install and configure both Chrome and ChromeDriver on GitHub Actions environments, specifically addressing the "DevToolsActivePort file doesn't exist" error. This issue typically occurs when Chrome, running in headless mode, cannot properly initiate due to mismatches or memory constraints. The first script tackles this by specifying a Chrome version and ensuring its compatibility with ChromeDriver, which is crucial for running Selenium tests. The initial commands perform an update of apt packages and use wget to fetch a specific version of Google Chrome from a mirror. Using a mirror ensures that the right version is installed, especially if the default repository lacks this version. This approach guarantees that a consistent version of Chrome is used across different test runs.

Next, the script proceeds to install a version-compatible ChromeDriver by isolating the major version from Chrome (e.g., "117" from "117.0.5938.62") using a command to parse it. This allows the script to fetch the exact ChromeDriver needed for that specific major version using a URL pattern designed for ChromeDriver releases. By making sure these versions align, the setup prevents mismatched versions from causing the ChromeDriver initialization failure, which often triggers the DevTools error. If ChromeDriver fails to download the specific version, the script includes a fallback option to download the latest release, maintaining flexibility. These steps are particularly useful in automated CI/CD pipelines where quick and reliable solutions are a priority 🔧.

After downloading, the script deletes any previously installed ChromeDriver from the system using “sudo rm -f” to avoid conflicts with older drivers. This ensures that only the correct version is in place, minimizing risks of version conflicts that can disrupt test stability. Permissions for ChromeDriver are also set to be executable, which is a necessary step for launching the driver in CI/CD environments. Using Chrome in “headless” mode with options like “--no-sandbox” and “--disable-dev-shm-usage” also reduces Chrome’s resource footprint. These options enable tests to run in environments with limited resources (e.g., cloud servers or CI pipelines) without causing Chrome to crash, which is one of the common causes behind the DevToolsActivePort error.

Finally, in the WebDriver setup, options like “--disable-gpu” and “--remote-debugging-port=9222” ensure a more stable Chrome run in headless mode. The “--disable-gpu” flag disables GPU rendering, which is unnecessary and sometimes problematic in headless mode. Meanwhile, the “--remote-debugging-port” option allows Chrome to open a debugging port essential for Selenium to connect to it in CI. In sum, this setup prevents common automation bottlenecks, enabling a more reliable and robust testing environment. As a result, these scripts make running headless Chrome on CI/CD systems a much smoother experience, ensuring automated tests run consistently without hiccups 🚀.

sudo apt-get update
sudo apt-get install -y wget apt-transport-https curl
CHROME_VERSION="117.0.5938.62"
CHROME_DEB="google-chrome-stable_${CHROME_VERSION}-1_amd64.deb"
wget https://mirror.cs.uchicago.edu/google-chrome/pool/main/g/google-chrome-stable/$CHROME_DEB
sudo dpkg -i $CHROME_DEB || sudo apt-get install -f -y
# Install ChromeDriver matching Chrome
sudo apt-get install -y wget unzip
MAJOR_VERSION=$(echo $CHROME_VERSION | cut -d '.' -f1)
LATEST_DRIVER=$(wget -qO- https://chromedriver.storage.googleapis.com/LATEST_RELEASE_$MAJOR_VERSION)
if [ -z "$LATEST_DRIVER" ]; then
  echo "Falling back to latest ChromeDriver version."
  LATEST_DRIVER=$(wget -qO- https://chromedriver.storage.googleapis.com/LATEST_RELEASE)
fi
sudo rm -f /usr/local/bin/chromedriver
wget https://chromedriver.storage.googleapis.com/$LATEST_DRIVER/chromedriver_linux64.zip
unzip chromedriver_linux64.zip
sudo mv chromedriver /usr/local/bin/
sudo chmod +x /usr/local/bin/chromedriver

// Import necessary libraries
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import io.github.bonigarcia.wdm.WebDriverManager;
// Set up ChromeDriver
WebDriverManager.chromedriver().setup();
ChromeOptions options = new ChromeOptions();
options.addArguments("--no-sandbox");
options.addArguments("--disable-dev-shm-usage");
options.addArguments("--headless");
options.addArguments("--disable-gpu");
options.addArguments("--remote-debugging-port=9222");
ChromeDriver driver = new ChromeDriver(options);
// Start Selenium test logic here
driver.quit();

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
class WebDriverTests {
  private WebDriver driver;
  @BeforeEach
  void setUp() {
    ChromeOptions options = new ChromeOptions();
    options.addArguments("--headless");
    options.addArguments("--no-sandbox");
    driver = new ChromeDriver(options);
  }
  @Test
  void testDriverInitialization() {
    driver.get("https://www.google.com");
    assertEquals("Google", driver.getTitle());
  }
  @AfterEach
  void tearDown() {
    driver.quit();
  }
}

Optimizing Selenium Tests with GitHub Actions and Headless Chrome

One important aspect of running headless Chrome with Selenium in CI/CD pipelines like GitHub Actions is understanding the environmental constraints. Running Chrome in headless mode means it operates without a graphical interface, making it perfect for CI environments. However, headless Chrome can be more sensitive to system configurations and requires additional setup compared to a local environment. The error, "DevToolsActivePort file doesn't exist," is commonly linked to a failure in Chrome's initialization, often due to memory constraints or configuration mismatches. Implementing memory-efficient configurations like --disable-dev-shm-usage and --no-sandbox helps overcome these issues and can significantly stabilize tests in memory-limited CI/CD environments.

To ensure compatibility, it’s essential to keep both Chrome and ChromeDriver versions aligned. Inconsistent versions are a frequent source of errors in GitHub Actions, as the runner might default to the latest version, which may not match ChromeDriver requirements. To address this, our solution includes parsing the major Chrome version to fetch the exact ChromeDriver version that corresponds, improving stability. Additionally, setting remote-debugging-port allows ChromeDriver to interact with the browser more reliably by enabling a communication port. This setup is essential when using GitHub Actions or similar tools to run automated browser tests on a virtual machine.

These configurations make a big difference in efficiency, reducing errors and improving the reliability of test runs. By ensuring resource-efficient options and using the correct versions, headless Chrome runs are much more likely to execute successfully, saving developers from dealing with frustrating errors mid-testing. Ultimately, robust configurations and compatible dependencies make the CI/CD testing experience smoother, enabling developers to focus on creating and improving their applications without the disruption of persistent setup issues 🚀.