CI builds should be more reliable when using Chrome Driver

[craigfowler]

This Claude prompt explains the issue:

I have a large number of unit tests for a project which uses .NET, Selenium and Chrome driver.
When I run the tests in CI I encounter frequent but intermittent build failures due to Chrome not starting up in a timely manner. Here's an example of a failure, but it's rarely the same tests which fail.

  Failed PerformAsAsyncShouldThrowIfWeDontWaitLongEnough(CSF.Screenplay.StageAdapter) [1 s]
  Error Message:
   System.InvalidOperationException : session not created: Chrome instance exited. Examine ChromeDriver verbose log to determine the cause. (SessionNotCreated)
  Stack Trace:
     at OpenQA.Selenium.WebDriver.UnpackAndThrowOnError(Response errorResponse, String commandToExecute)
   at OpenQA.Selenium.WebDriver.Execute(String driverCommandToExecute, Dictionary`2 parameters)
   at OpenQA.Selenium.WebDriver.StartSession(ICapabilities desiredCapabilities)
   at OpenQA.Selenium.WebDriver..ctor(ICommandExecutor executor, ICapabilities capabilities)
   at OpenQA.Selenium.Chromium.ChromiumDriver..ctor(ChromiumDriverService service, ChromiumOptions options, TimeSpan commandTimeout)
   at OpenQA.Selenium.Chrome.ChromeDriver..ctor(ChromeDriverService service, ChromeOptions options, TimeSpan commandTimeout)
   at OpenQA.Selenium.Chrome.ChromeDriver..ctor(ChromeOptions options)
   at InvokeStub_ChromeDriver..ctor(Object, Span`1)
   at System.Reflection.MethodBaseInvoker.InvokeWithOneArg(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture)
1)    at OpenQA.Selenium.WebDriver.UnpackAndThrowOnError(Response errorResponse, String commandToExecute)
   at OpenQA.Selenium.WebDriver.Execute(String driverCommandToExecute, Dictionary`2 parameters)
   at OpenQA.Selenium.WebDriver.StartSession(ICapabilities desiredCapabilities)
   at OpenQA.Selenium.WebDriver..ctor(ICommandExecutor executor, ICapabilities capabilities)
   at OpenQA.Selenium.Chromium.ChromiumDriver..ctor(ChromiumDriverService service, ChromiumOptions options, TimeSpan commandTimeout)
   at OpenQA.Selenium.Chrome.ChromeDriver..ctor(ChromeDriverService service, ChromeOptions options, TimeSpan commandTimeout)
   at OpenQA.Selenium.Chrome.ChromeDriver..ctor(ChromeOptions options)
   at InvokeStub_ChromeDriver..ctor(Object, Span`1)
   at System.Reflection.MethodBaseInvoker.InvokeWithOneArg(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture)
  Standard Output Messages:
 Connection refused (localhost:45651)
 Connection refused (localhost:45651)
 Connection refused (localhost:45651)
 Connection refused (localhost:45651)
 Connection refused (localhost:45651)
 Connection refused (localhost:45651)
 Connection refused (localhost:45651)

This happens in CI when running tests with GitHub actions on a Linux OS.

Are there any techniques I could use to make these more reliable?

[craigfowler]

Here's the response:

This is a classic "Chrome startup race condition" problem in CI. Here are the most effective techniques to address it:

Chrome Options for CI Stability

The most impactful fix is ensuring Chrome is configured properly for a headless Linux CI environment. Make sure you're passing these options when creating your ChromeDriver:

var options = new ChromeOptions();
options.AddArgument("--headless=new");       // Use newer headless mode
options.AddArgument("--no-sandbox");          // Required in CI/Docker
options.AddArgument("--disable-dev-shm-usage"); // Avoids /dev/shm size limits crashing Chrome
options.AddArgument("--disable-gpu");
options.AddArgument("--disable-extensions");
options.AddArgument("--disable-software-rasterizer");
options.AddArgument("--remote-debugging-port=0"); // Avoids port conflicts

The --disable-dev-shm-usage flag is often the single biggest fix — by default Chrome uses /dev/shm for shared memory, which is typically very small in GitHub Actions and causes silent crashes.

Retry Logic on Driver Instantiation

Since the failure is intermittent, a retry wrapper around ChromeDriver construction is pragmatic:

public static ChromeDriver CreateDriverWithRetry(ChromeOptions options, int maxAttempts = 3)
{
    for (int attempt = 1; attempt <= maxAttempts; attempt++)
    {
        try
        {
            return new ChromeDriver(options);
        }
        catch (InvalidOperationException ex) when (attempt < maxAttempts
            && ex.Message.Contains("session not created"))
        {
            Thread.Sleep(TimeSpan.FromSeconds(attempt * 2)); // Back off between retries
        }
    }
    throw new InvalidOperationException("ChromeDriver failed to start after retries.");
}

Increase the Command Timeout

The default timeout for ChromeDriver to start a session is 60 seconds, but you can be explicit about it — and raise it if your CI runners are slow:

var service = ChromeDriverService.CreateDefaultService();
service.EnableVerboseLogging = true; // Helps diagnose future failures
service.LogPath = "chromedriver.log";

var driver = new ChromeDriver(service, options, commandTimeout: TimeSpan.FromSeconds(90));

Limit Test Parallelism

If you're running many tests in parallel, you'll get port conflicts and resource exhaustion as multiple Chrome instances race to start. In your xunit.runner.json or [assembly: CollectionBehavior] attribute, cap parallelism:

// xunit.runner.json
{
  "parallelizeAssembly": false,
  "parallelizeTestCollections": true,
  "maxParallelThreads": 2
}

Or if using NUnit, control it via [assembly: LevelOfParallelism(2)]. The right number depends on your runner's CPU count — GitHub Actions' standard runners have 2 cores, so 2–4 is usually the ceiling before things degrade.

Use a Unique Port per Driver Instance

Collisions on ChromeDriver's default port are a common source of the "connection refused" errors you're seeing. Force each instance to pick a free port:

var service = ChromeDriverService.CreateDefaultService();
service.Port = FindFreePort(); // See below

static int FindFreePort()
{
    using var listener = new System.Net.Sockets.TcpListener(
        System.Net.IPAddress.Loopback, 0);
    listener.Start();
    int port = ((System.Net.IPEndPoint)listener.LocalEndpoint).Port;
    listener.Stop();
    return port;
}

GitHub Actions Specific: Pre-warm Chrome

You can add a step to your workflow to verify Chrome is available and functional before tests run, catching environment issues early rather than mid-suite:

- name: Verify Chrome is available
  run: |
    google-chrome --version
    google-chrome --headless --no-sandbox --disable-dev-shm-usage \
      --dump-dom about:blank > /dev/null

---

Recommended priority order: Start with --disable-dev-shm-usage + --no-sandbox, then add retry logic, then cap parallelism. Those three together resolve this problem in the vast majority of CI setups.