Selenium ChromeDriver: Setup and Automation Testing Guide

Short answer: With a current Selenium release, install the language binding and create a Chrome WebDriver without specifying a driver path. Selenium Manager, included with Selenium since version 4.6, can discover Chrome, resolve a compatible ChromeDriver, download it, and cache it. Set an explicit driver path when you need a fixed executable, use a custom browser installation, or cannot use Selenium Manager’s network or platform support.

1. What ChromeDriver does

ChromeDriver is the separate executable Selenium WebDriver uses to control Chrome. Your test code calls Selenium APIs; the browser-specific driver acts as the bridge to the browser. ChromeDriver and Chrome need compatible versions. Chrome’s getting-started guide explains the driver and setup.

2. Recommended setup: let Selenium Manager find the driver

Selenium Manager ships with Selenium and runs as a fallback when a driver has not already been supplied. For a standard local setup, install or update the Selenium binding, ensure Chrome is installed, and create a Chrome driver using the normal API. You generally do not need a separate driver-manager package or a manually downloaded binary.

Python

Install Selenium:

python -m pip install -U selenium

Save as smoke_test.py and run with python smoke_test.py:

from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--headless=new")  # Optional; remove to see the browser.

driver = webdriver.Chrome(options=options)
try:
    driver.get("https://example.com")
    print("Title:", driver.title)
finally:
    driver.quit()

The Python Selenium API documents webdriver.Chrome() as the browser entry point. See the Python API documentation.

JavaScript (Node.js)

Install the Selenium package:

npm install selenium-webdriver

Save as smoke-test.js and run with node smoke-test.js:

const { Builder, Browser } = require('selenium-webdriver');

(async function main() {
  const driver = await new Builder().forBrowser(Browser.CHROME).build();
  try {
    await driver.get('https://example.com');
    console.log('Title:', await driver.getTitle());
  } finally {
    await driver.quit();
  }
})();

This is the JavaScript API’s standard builder pattern. See the Selenium JavaScript API.

Java

Install Selenium using the dependency mechanism already used by your project, then create a driver without setting webdriver.chrome.driver. For example, with Selenium on the classpath:

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class SmokeTest {
    public static void main(String[] args) {
        WebDriver driver = new ChromeDriver();
        try {
            driver.get("https://example.com");
            System.out.println("Title: " + driver.getTitle());
        } finally {
            driver.quit();
        }
    }
}

Use a current Selenium version so Selenium Manager is available. Other Selenium bindings follow the same general approach but use their own APIs.

3. Install and configure ChromeDriver manually

Manual management is useful when a build requires a pinned driver, the browser is installed in a custom location, a package-managed browser is not detected, or the environment cannot use Selenium Manager. Chrome recommends ensuring Chrome or Chromium is installed in a recognized location, obtaining the matching ChromeDriver for the platform, and making the executable discoverable. See Chrome’s setup steps.

Identify the installed Chrome or Chromium version and platform architecture.
Choose a compatible ChromeDriver for that browser version and release channel.
Place the driver in a controlled directory, and either add that directory to PATH or configure its explicit path in Selenium.
Keep the browser and driver versions aligned when updating either one.

For Chrome versions M115 and newer, Chrome for Testing publishes Chrome and ChromeDriver releases together by channel. Use the official ChromeDriver documentation and its Chrome for Testing availability data to select a release; do not assume an arbitrary “latest” driver matches every installed Chrome.

Python with an explicit driver path

from selenium import webdriver
from selenium.webdriver.chrome.service import Service

service = Service(executable_path="/opt/chromedriver/chromedriver")
driver = webdriver.Chrome(service=service)
try:
    driver.get("https://example.com")
    print(driver.title)
finally:
    driver.quit()

Java with an explicit driver path

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.chrome.ChromeDriverService;
import java.io.File;

public class PinnedDriverTest {
    public static void main(String[] args) {
        ChromeDriverService service = new ChromeDriverService.Builder()
            .usingDriverExecutable(new File("/opt/chromedriver/chromedriver"))
            .build();
        WebDriver driver = new ChromeDriver(service, new ChromeOptions());
        try {
            driver.get("https://example.com");
            System.out.println(driver.getTitle());
        } finally {
            driver.quit();
        }
    }
}

Use the path syntax and service options appropriate to your operating system and Selenium binding. Another documented Java configuration is the webdriver.chrome.driver system property.

cURL and direct Node.js driver setup

cURL cannot create a Selenium WebDriver session: ChromeDriver speaks the WebDriver protocol, and cURL alone does not install a browser, driver, or Selenium client. Use cURL to inspect a driver service only after you have started ChromeDriver, for example:

curl http://localhost:9515/status

For Node.js, the runnable Selenium Manager example is the builder example above. It intentionally does not specify a driver path; provide a configured ChromeDriver service through the Selenium JavaScript API only when your environment requires manual management.

4. Choose automatic or manual management

Consideration	Selenium Manager	Manual driver path
Maintenance	Discovers, downloads, and caches a driver using browser vendor metadata.	Your team maintains the executable, path, and version alignment.
Control	Convenient when the browser is detectable and metadata endpoints are reachable.	Lets a build pin a specific executable and choose its location.
Network policy	May need access to metadata and artifact download endpoints; proxy settings can matter.	Can work with pre-provisioned binaries where runtime downloads are restricted.
Custom browser or architecture	May not recognize package-managed installations or support every architecture.	Explicit paths can accommodate custom layouts, if compatible binaries are available.

5. Run ChromeDriver reliably in automation tests

Always close the session. Put driver.quit() in a finally block or equivalent teardown hook so failed assertions do not leave browser processes behind.
Prefer explicit waits to arbitrary sleeps. Wait for the condition your test needs, such as an element becoming visible, instead of guessing a delay. This reduces needless waiting and timing-dependent failures.
Use headless mode only when useful. It can suit CI environments without a desktop; remove the option when diagnosing behavior that needs visual inspection.
Keep CI inputs stable. Pin or control browser updates when reproducibility matters, and make the driver selection strategy explicit for the environment.
Provision system dependencies. A downloaded browser or driver can still fail to start if the Linux image lacks required shared libraries.
Do not share one WebDriver session across parallel tests. Give each test worker its own browser session and clean it up.

Performance depends on browser startup, page load behavior, the page itself, and your test waits. Selenium Manager caches the downloaded executable, so later launches do not need to repeat the same driver download. Browser startup remains per session; reuse a session only where test isolation and your framework’s lifecycle allow it.

6. Troubleshooting

Symptom	Likely cause	What to do
“Unable to locate driver” or driver not found	The binding cannot find a configured executable, or a stale path points nowhere.	Remove stale driver path configuration and let a current Selenium Manager resolve it, or set the correct explicit path. See Selenium’s driver troubleshooting guide.
Chrome and ChromeDriver report incompatible versions	The manually managed driver does not match the installed browser release.	Check Chrome’s version and channel, then select the corresponding driver from Chrome for Testing metadata, particularly for M115 and later.
Selenium Manager cannot download metadata or binaries	A proxy, firewall, or restricted network blocks vendor endpoints.	Check network policy and configure the proxy as documented by Selenium, including `SE_PROXY` where applicable. Alternatively, provision a compatible driver and use its explicit path.
Browser installed by Snap, Anaconda, or another package manager is not detected	The browser executable or profile layout differs from the expected location.	Configure the browser binary and driver locations explicitly using options supported by your Selenium binding.
Manager fails on Linux ARM64/aarch64 or another uncommon architecture	The standard Selenium Manager binary may not cover that architecture.	Use a compatible explicit driver path or a custom Selenium Manager binary; Selenium documents `SE_MANAGER_PATH` for a custom manager binary.
Chrome starts locally but fails in a minimal Linux container	Required shared libraries or other system packages are missing.	Install the dependencies required by the chosen browser build and distribution. Check the browser’s launch output for the missing library instead of applying a universal package list.
Tests hang or leave Chrome processes behind	A session is not closed after an error, or the test waits for a condition that never occurs.	Call `quit()` in teardown/finally and use bounded condition-based waits with useful timeout diagnostics.

7. When a screenshot API is a better fit

Selenium is appropriate when a test must interact with a browser: click controls, inspect application state, or verify a workflow. If the task is simply to capture a page as an image or PDF, a screenshot API can avoid managing browser and driver processes in your application.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.

8. FAQ

Do I need to download ChromeDriver separately?

Usually not with a current Selenium release and a supported environment. Selenium Manager can resolve and cache the driver. Download and configure it yourself when you need a fixed binary or automatic management cannot work.

Is ChromeDriver the same as Chrome?

No. Chrome is the browser; ChromeDriver is the separate executable Selenium uses to control it.

Can Selenium test Chromium instead of Google Chrome?

Yes, when the Chromium browser binary and a compatible driver are available and configured for the environment.

Does ChromeDriver itself test my site?

No. It provides browser control. Your Selenium test code performs actions and checks expected behavior.