HowToCodePage

WebDriver setup

How Selenium actually drives a browser: the client library, the driver binary and the browser, plus how to get a session running reliably.

The three moving parts

Selenium is a client library that speaks the W3C WebDriver protocol over HTTP. A driver binary - chromedriver, geckodriver, msedgedriver - translates those commands into actions in a real browser. Your test code never touches the browser directly.

  • Client library: your language binding, such as the Python, Java, C# or JavaScript package.
  • Driver binary: one per browser family, matched to the installed browser version.
  • Browser: the real application, launched with a clean profile so tests do not inherit your cookies and extensions.
# pip install selenium
from selenium import webdriver

driver = webdriver.Chrome()        # Selenium Manager resolves the driver binary
driver.get("https://example.com")
print(driver.title)
driver.quit()

Getting a session reliably

import pytest
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

@pytest.fixture
def driver():
    options = Options()
    options.add_argument("--headless=new")   # run without a window on CI
    options.add_argument("--no-sandbox")
    d = webdriver.Chrome(options=options)
    d.implicitly_wait(0)                     # keep waits explicit
    yield d
    d.quit()                                 # always close the session
ProblemCauseFix
SessionNotCreatedExceptionBrowser and driver versions do not matchLet Selenium Manager resolve it, or pin both versions in the CI image
Browser not foundThe browser is installed in a non-standard pathSet the binary location in the options
Passes locally, hangs on CINo display in the containerRun headless and raise the shared memory size for the container
Second run fails to startA previous session was never quitQuit in a fixture teardown, and fail the suite on leaked processes
⚠️
Always call driver.quit() in teardown. Leaked sessions leave browser processes behind, and a CI runner that accumulates them starts failing in ways that look like test flakiness.

FAQ

Do I still need to download chromedriver manually?
Rarely. Selenium Manager, included from version 4.6, resolves and caches the right driver automatically. Pin it explicitly only when you need a reproducible CI image.
Which browser should I test?
Whatever your users actually use. Chromium is the cheapest to run headless; add Firefox and WebKit only where the risk justifies the extra maintenance.

Locators and waits A real test example

Last refreshed 2026-09-18.