How to Run Selenium WebDriver in CI

Selenium needs a browser plus a matching driver. Modern Selenium can auto-provision drivers, but the browser and its libraries are still on you.

Selenium 4 ships Selenium Manager, which resolves a compatible driver automatically. In CI you still install the browser, its system libraries, and run headless - or use a Selenium service container.

Why it fails in CI

Browser/driver version mismatch → session not created: ... browser version.
The browser is missing its OS libraries → it cannot launch.
No display and no headless flag → the browser refuses to start.

Install it reliably

Let Selenium Manager resolve the driver, install the browser with its deps, and run headless. Alternatively, run the official Selenium Docker service.

Terminal

# install the browser + deps (Chromium shown)
apt-get update && apt-get install -y chromium fonts-liberation libnss3 libgbm1

# Selenium 4 auto-resolves the driver via Selenium Manager
# Python example, run headless:
python -c "from selenium import webdriver; o=webdriver.ChromeOptions(); o.add_argument('--headless=new'); o.add_argument('--no-sandbox'); webdriver.Chrome(options=o).quit()"

Cache & speed

Bake the browser and libraries into a custom image. If you use a Selenium service container, pin its tag. Browser launches are flaky; auto-retry and larger managed runners reduce churn.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/selenium
    key: selenium-${{ runner.os }}-${{ hashFiles('**/requirements*.txt','**/package-lock.json') }}

Common errors

session not created: This version of ChromeDriver only supports Chrome version N → let Selenium Manager pick the driver, or pin both.
unknown error: Chrome failed to start → missing libs or missing --no-sandbox.
WebDriverException: ... not in PATH → use Selenium Manager or place the driver on PATH.

Key takeaways

Selenium 4 auto-resolves drivers via Selenium Manager - match the browser to it.
Install the browser libraries and run --headless --no-sandbox in containers.
A Selenium service container is a clean alternative to local browsers.