How to Run Selenium WebDriver in CI

Selenium failures in CI almost always come down to two things: a driver/browser version mismatch and a browser that cannot start in a container.

Selenium WebDriver drives a real browser through a separate driver binary (chromedriver/geckodriver). In CI the driver version must match the installed browser, and the browser needs headless + sandbox options. Selenium Manager (4.6+) automates the first half.

Why it fails in CI

If the driver and browser major versions differ you get SessionNotCreatedException: This version of ChromeDriver only supports Chrome version N. If the browser cannot launch in the container you get chrome not reachable or unknown error: DevToolsActivePort file doesn’t exist - the same sandbox/shm issues that hit raw Chrome.

Install & run it reliably

Let Selenium Manager resolve the matching driver (built into Selenium 4.6+, no manual chromedriver download), and pass the container-safe browser options. If instead you install the browser and driver yourself, pin them together - a fixed Chrome version and the chromedriver build for that exact major; a floating chromedriver against an auto-updated Chrome is the classic CI break.

selenium (python)

from selenium import webdriver
opts = webdriver.ChromeOptions()
opts.add_argument('--headless=new')
opts.add_argument('--no-sandbox')
opts.add_argument('--disable-dev-shm-usage')
driver = webdriver.Chrome(options=opts)  # Selenium Manager finds the driver

Cache & speed

Cache the driver binaries Selenium Manager downloads (under ~/.cache/selenium) keyed on browser version. For parallel suites, run a Selenium Grid container (selenium/standalone-chrome) as a CI service so every test reuses one warmed browser pool instead of launching fresh.

Common errors

SessionNotCreatedException: only supports Chrome version N → driver/browser mismatch; let Selenium Manager pick or pin both.
chrome not reachable → add --no-sandbox --disable-dev-shm-usage.
DevToolsActivePort file doesn’t exist → sandbox or shm; same flags.
WebDriverException: Message: unknown error: cannot connect → the browser never started; check libs and flags.

Key takeaways

Use Selenium Manager (4.6+) so the driver matches the browser automatically.
Pass --headless=new --no-sandbox --disable-dev-shm-usage for containers.
A selenium/standalone-chrome Grid service speeds up parallel suites.