How to Run chromedriver in CI (Version Matching)

The chromedriver/Chrome version pairing is the single most common CI break in browser testing. Chrome for Testing solves it by versioning both together.

chromedriver only supports the Chrome major version it was built for. CI images update Chrome on their own schedule, so a pinned driver drifts and sessions stop opening. The durable fix is to install a matched pair.

Why it fails in CI

When the runner’s Chrome updates past your chromedriver, you get SessionNotCreatedException: This version of ChromeDriver only supports Chrome version N. Current browser version is M. It passes one day and breaks the next with no code change - the runner image simply bumped Chrome.

Install & run it reliably

Use Chrome for Testing, which publishes Chrome and chromedriver at identical, downloadable versions. The @puppeteer/browsers CLI fetches a matched pair:

chrome-for-testing

npx @puppeteer/browsers install chrome@stable
npx @puppeteer/browsers install chromedriver@stable
# both resolve to the same version -> no mismatch

Or let the test framework manage it

Selenium Manager (Selenium 4.6+) and WebdriverIO’s driver service both auto-resolve the right chromedriver for the installed Chrome. If you use either, do not also pin chromedriver manually - that reintroduces the drift. Cache the downloaded Chrome + chromedriver binaries keyed on the resolved version string so you do not re-download each run, and avoid the chromedriver npm package’s floating "latest" behavior in CI.

Common errors

only supports Chrome version N. Current browser version is M → install a matched pair (Chrome for Testing).
DevToolsActivePort file doesn’t exist → add --no-sandbox --disable-dev-shm-usage.
chromedriver: command not found → the binary is not on PATH; reference its full path.
Works locally, breaks in CI overnight → the runner image bumped Chrome under a pinned driver.

Key takeaways

chromedriver must match the Chrome major version exactly.
Chrome for Testing distributes both at the same version - use it.
If a test framework manages drivers, do not pin chromedriver yourself.