ChromeDriver

Description

When Selenium 2.0 was shipped in July 2011, it introduced a new model to automate browsers: instead of injecting JavaScript directly into pages to simulate user actions, it sent commands to a standalone server process that controlled the browser from the outside. Each major browser had to have its own version of that server. ChromeDriver was Google’s implementation for Chrome and was released along with Selenium 2.0 in the same year.

The problem which ChromeDriver set out to solve was a simple one. Chrome had become fast and had taken a big chunk of the browser market, but web developers who were creating automated tests were not able to reliably control it from code. Previous approaches to automation had been bound to Chrome, either by running within the browser’s JavaScript context — which limited what they could see — or by simulating inputs at the operating system level that could not differentiate between elements in the browser. ChromeDriver opened a proper programmatic channel to Chrome’s internals, allowing test scripts to navigate pages, click elements, fill out forms, read DOM state, execute JavaScript, and watch network activity via a stable API.

The tool is implemented as a stand-alone http server. Test code in Java, Python, Ruby, C#, JavaScript or any other language supported by Selenium sends commands as http requests to ChromeDriver, which translates them into Chrome DevTools Protocol (CDP) messages and sends them to Chrome over a WebSocket connection. From the perspective of the script, the browser is a machine to be controlled: predictable, queryable and scriptable.

HOW IT WORKS

ChromeDriver starts Chrome using a series of command-line arguments that open a remote debugging port. Once Chrome opens that port, ChromeDriver creates a WebSocket connection and uses CDP to give instructions and receive events. The protocol allows ChromeDriver to do things that external input simulation never could — inspect the live DOM tree, intercept network requests, read output from the console, evaluate JavaScript expressions in particular frame contexts, and observe page lifecycle events as they fire.

ChromeDriver provides support for the standard W3C WebDriver capabilities — browser name, version, page loading strategy — and adds Chromium-specific options via the ChromeOptions object. Through ChromeOptions, scripts send command-line arguments to Chrome on startup, install Chrome extensions, set paths to non-standard Chrome installations, set up proxies, and control whether Chrome runs in headless mode.

Headless mode eliminates the visible browser window — Chrome uses the full engine, but outputs nothing to a display, making it useful on servers and CI pipelines that lack monitors. The original headless implementation was released in Chrome 59 in 2017. Chrome 112 in 2023 replaced it with a rewritten version that uses the same rendering pipeline as the standard browser, filling in the gaps where headless page behavior previously differed from visible sessions.

THE W3C STANDARD TRANSITION

The history of ChromeDriver is divided at the W3C standardization of WebDriver. Before standardization, ChromeDriver used the JSON Wire Protocol, an informal specification from the development of Selenium. It worked, but was inconsistently implemented across drivers, meaning that tests that ran in Chrome sometimes failed in Firefox or Safari.

The W3C WebDriver specification formalized the protocol in 2018. ChromeDriver 75 was released in 2019 and made W3C compliance the default. The change required test code updates in places — capabilities with informal naming needed renaming (loggingPrefs became goog:loggingPrefs), and cookie handling aligned more strictly to spec. For teams that have existing tests, the transition was a source of friction. For the wider ecosystem, it made Chrome automation behaviour more predictable and portable across browsers.

VERSION MATCHing and Chrome for Testing

For most of ChromeDriver’s history, Google had a separate release process from Chrome. Users had to know which version matched, download the appropriate version from a Google Cloud Storage bucket, and put it in a location where their automation framework could locate it. Version numbers matched — ChromeDriver 73 ran Chrome 73, ChromeDriver 114 ran Chrome 114 — but the separate distribution meant version drift was a constant operational issue. Chrome updated automatically, ChromeDriver did not.

In 2023, Google incorporated ChromeDriver in the Chrome for Testing (CfT) initiative. Starting with Chrome 115, the release of ChromeDriver became part of the same release infrastructure as Chrome itself. The Chrome for Testing dashboard at googlechromelabs.github.io/chrome-for-testing releases matched Chrome and ChromeDriver binaries for each release in four channels: Stable, Beta, Dev, and Canary. JSON API endpoints on the same infrastructure allow automation pipelines to query the available versions and download URLs programmatically.

Chrome for Testing also includes a headless-first Chrome binary that is packaged for automation environments. Unlike regular Chrome, the CfT Chrome binary doesn’t automatically update, which is important for CI pipelines that require a fixed and reproducible version of the browser. A test run using Chrome for Testing 130 today will use the same binary and the same ChromeDriver tomorrow, no background update changing behavior between runs.

WEBDRIVER BIDI

ChromeDriver currently implements two protocols: the W3C WebDriver Classic, the command-response protocol using the W3C standard over the WebSocket protocol and implemented over the WebDriver protocol, which has been in place since 2018, and WebDriver BiDi (Bidirectional) which is a newer protocol the W3C Browser Testing and Tools Working Group initiated standardizing in 2020.

Classic WebDriver works in one direction only, the test script sends a command, ChromeDriver executes it, and returns a result. The model works well for most testing scenarios but has trouble capturing events as they occur. Observing the output on the console, monitoring network requests in real-time, or reacting to events on a page as they fire were either polling or using CDP directly, which is Chromium-specific and not portable to other browsers.

WebDriver BiDi uses WebSockets to implement two-way communication. The browser does not have to wait for a command from the test client to ask for events and can push events to the test client. Console messages, JavaScript errors, network activity, and DOM mutations flow to the test script as they happen. Because BiDi is based on an open W3C standard, the same test code runs across Chrome, Firefox, and Safari — browsers that all have their own driver (ChromeDriver, GeckoDriver, WebKitDriver) but all implement the same BiDi protocol.

ChromeDriver includes BiDi support growing side-by-side with Classic WebDriver, growing alongside the W3C specification as browser vendors and the standards body finalize remaining modules.

USAGE AND ECOSYSTEM

ChromeDriver supports all major test frameworks that support Selenium WebDriver. In Python a test imports webdriver and creates an instance of Chrome, in Java the same using the Selenium Java bindings, in JavaScript, WebDriverIO and Nightwatch both use ChromeDriver under the hood. Playwright and Puppeteer work directly with Chromium communication through CDP and bypass ChromeDriver, while they both communicate with the same Chrome binary.

Selenium Manager introduced in Selenium 4.6 in 2022 helps to automate the version matching problem. It checks the installed version of Chrome, downloads the corresponding version of ChromeDriver binary automatically and sets the path — no need to manually write version tracking scripts.

ChromeDriver supports remote execution using Selenium Grid. Grid nodes run ChromeDriver locally, accept sessions from the hub and let tests be run in parallel across machines or in cloud platforms such as BrowserStack, Sauce Labs and LambdaTest. The test script is connected to the remote grid end point; the rest of the API remains the same.