ChromeDriver is a standalone server that lets automated tests and scripts control Google Chrome and Chromium. It implements the W3C WebDriver standard and WebDriver BiDi. A test written with Selenium or another WebDriver client can therefore open pages, click elements, type text and read results in a real Chrome browser. ChromeDriver runs on Windows, macOS and Linux, drives Chrome on desktop systems, ChromeOS and Android, and is free. It is developed as part of the Chromium project.
How tests talk to Chrome
ChromeDriver sits between a test and the browser. A test written in a language such as Java or Python uses a WebDriver client library to send standard WebDriver commands to ChromeDriver. ChromeDriver carries them out in Chrome and returns the results.
A new session normally starts a fresh Chrome window with a temporary user profile, so each test begins from a clean state. When the test calls quit, ChromeDriver closes the browser and removes that temporary profile.
Ways to run the server
You can start ChromeDriver in three ways, and the choice mostly affects speed in large suites:
- Managed by the driver class. The client library starts the ChromeDriver process when a driver object is created and stops it on quit. It is the simplest setup, but a new server per test adds time.
- Service mode. The test code starts one ChromeDriver service, often on any free port, and reuses it for many browser sessions before stopping it at the end.
- Standalone. You start ChromeDriver from a terminal before the tests run. It prints the port it listens on, and tests connect to it as a remote WebDriver endpoint.
By default ChromeDriver accepts connections only from the local machine. An allowed-IPs switch opens it to specific remote addresses. Since it fully controls a browser, ChromeDriver is best run under a low-privilege test account, ideally in a container or virtual machine.
Configuring Chrome with ChromeOptions
ChromeDriver adds Chrome-specific settings to the standard WebDriver capabilities. Client libraries expose them through a ChromeOptions class, or through a goog:chromeOptions dictionary where no such class exists. These options decide how the browser is launched and what state it starts in:
- Command-line arguments for Chrome, such as a window size or starting maximized, and a list of default switches ChromeDriver should not pass, for example to re-enable the pop-up blocker.
- A path to a specific Chrome binary instead of the default installation.
- Profile preferences, such as a default download folder, or a persistent profile folder when a test needs saved cookies or settings.
- A detach setting that keeps Chrome open after ChromeDriver itself exits.
Attaching to a running browser
Instead of launching Chrome, ChromeDriver can connect to a browser that is already running with remote debugging enabled. This requires the browser’s host and port. Some commands, such as resizing the window, fail in this mode. These commands rely on a helper that ChromeDriver loads only when it launches Chrome itself.
Extensions and mobile views
Tests can load Chrome extensions at startup, either as packed .crx files or as an unpacked folder containing a manifest. A separate option lets ChromeDriver see and switch into extension pages and other extension targets, which it hides by default.
Mobile emulation shows how a site renders on a phone without a physical device. ChromeDriver can take a device name from the list in Chrome DevTools. Alternatively, it can use a custom set of screen width, height and pixel ratio together with a user agent and client hints. It does not reproduce a phone’s GPU performance, browser interface behavior such as a hiding address bar, or hardware events like orientation changes.
Chrome and WebView on Android
ChromeDriver can also drive Chrome on an Android device, along with apps that display web content through WebView. The app must have web debugging and JavaScript enabled. The computer running ChromeDriver talks to the device through the Android Debug Bridge. Tests name the target app by its package name and can pick a specific device by serial number or attach to an app that is already running. With several devices connected, ChromeDriver assigns each new session a free one.
Logs and performance data
Out of the box, ChromeDriver reports only warnings and errors. A verbose switch records every command and response, and a log-path switch writes the output to a file, which helps trace a failing test.
The optional performance log gives tests access to browser activity that WebDriver commands do not expose. When enabled for a session, it collects Chrome DevTools events from the Network and Page domains, and can also record trace data for chosen trace categories. Tests read the entries as JSON messages through the WebDriver log interface, for example to inspect network requests during a run.
Matching ChromeDriver to Chrome
Each ChromeDriver build is tied to a Chrome version. ChromeDriver is available through Chrome for Testing, a set of Chrome builds made for automation. Each release channel offers matching ChromeDriver and headless shell builds. Lookup endpoints return the right ChromeDriver for a given Chrome build, so test setups can keep the two in step.
