Selenium Ecosystem, Installation, and First WebDriver Session: Core Concepts and Mental Model

1. Why installation folklore causes flaky automation

“Install Selenium” sounds like one action, but browser automation crosses several independently versioned layers. Your Python project contains the Selenium binding. The operating system provides—or Selenium Manager may manage—a browser. A browser-specific driver implements the WebDriver remote end for that browser. The binding creates a session through that driver and sends commands. If a team treats all of those as one package called “Selenium,” failures become mysterious and machine-specific.

A reproducible setup records the identity of each layer. The useful question is not “Does Selenium work on my laptop?” It is “Which binding created which session against which browser and driver, under which options and environment, and did the session terminate cleanly?”

2. The ecosystem and first-session mental model

flowchart TD
  P["Python project"] --> B["selenium 4.47.0 binding"]
  B --> M["Selenium Manager when driver is unavailable"]
  M --> D["Browser driver / WebDriver remote end"]
  D --> R["Browser binary"]
  B --> S["WebDriver session"]
  S --> D
  R --> A["Loopback AUT"]
  S --> E["Capabilities + session evidence"]

The binding is the API your Python code imports. Selenium Manager is a Rust CLI shipped with Selenium and invoked by the binding when driver management is needed. The browser driver is the browser-specific WebDriver implementation. The browser binary is the actual Chrome, Firefox, Edge, Safari, or another supported browser. The WebDriver session is the negotiated runtime relationship that exists only after session creation succeeds.

Selenium Server/Grid is a different boundary: it is required for remote/distributed WebDriver execution, not for the simple local webdriver.Chrome() path used here.

3. Objects, state stores, and ownership

The following table organizes the key choices and evidence for Objects, state stores, and ownership. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

4. Selenium Manager: default automation, not magic

Current Selenium bindings use Selenium Manager by default when a required browser driver is unavailable. Its driver-management path discovers the installed browser version, resolves the corresponding driver version using browser-vendor metadata, downloads the driver when needed, and stores it in a local cache (by default ~/.cache/selenium). It can also manage supported browser binaries when needed.

That automation removes a large amount of manual setup, but it creates observable dependencies: first-run network access may be needed, corporate proxies can block resolution, cache state affects repeat runs, and a manually supplied driver path or usable driver on the machine can change which executable is selected. The correct production habit is to record the resulting capabilities and Manager/driver diagnostics when a session cannot start.

5. Session creation and quit are one correctness contract

webdriver.Chrome() is not merely a Python constructor. It initiates driver resolution, starts a local driver service, launches or connects to a browser, negotiates capabilities, and creates a session identifier. Every command after that is scoped to the live session. driver.quit() asks the remote end to close every browser window in that session and terminate the session. If your test raises an exception before teardown and you have no finally or framework fixture, you may leave browser/driver processes behind.

from selenium import __version__ as selenium_version
from selenium import webdriver

print(f"selenium={selenium_version}")

driver = None
try:
    driver = webdriver.Chrome()
    caps = driver.capabilities
    print(f"session_id={driver.session_id}")
    print(f"browser={caps.get('browserName')}")
    print(f"browser_version={caps.get('browserVersion')}")
    print(f"platform={caps.get('platformName')}")
    chrome = caps.get('chrome', {})
    print(f"chromedriver={chrome.get('chromedriverVersion', 'not-reported')}")
finally:
    if driver is not None:
        driver.quit()

This script performs a read-only environment inspection. It does not navigate to a public site. The returned values are more useful than guessing from package names because they describe the session Selenium actually created.

6. Selenium Server/Grid is not part of the local installation path

For a local session, the Python binding talks to a locally managed driver service. For a remote session, the binding talks to Selenium Server/Grid or another WebDriver-compatible remote endpoint. The remote service then decides where the browser session runs. Installing the selenium Python package does not automatically mean Grid is running, and downloading Selenium Server is not required to automate one local browser.

Chapter 19 introduces Grid architecture. Chapter 02 deliberately keeps the local boundary small so a first failure can be attributed to the binding/Manager/driver/browser/session chain instead of distributed infrastructure.

7. DevOps connection: environment provenance is release evidence

A green browser test is difficult to trust when nobody can reproduce the environment that produced it. Record the Selenium binding version, Python version, browser name/version, driver version when reported, platform, relevant options, target environment, and test-data identity. In CI, preserve that alongside the test result. This makes a later red build diagnosable as an application regression, environment drift, browser rollout, or automation defect instead of an undifferentiated failure.

Knowledge check

Official references and version notes

• Selenium 4.47 release notes — release baseline for this chapter.
• Selenium downloads — current stable language bindings and Selenium Server/Grid status.
• Install a Selenium library — project dependency installation and the current selenium==4.47.0 example.
• WebDriver getting started and first script — browser/driver roles and first-session lifecycle.
• Selenium Manager — automated driver/browser discovery, download, cache, configuration, proxy, offline, PATH-skip, debug, and cache settings.
• Driver Service class — explicit local driver-service configuration and logging.
• Browser options — W3C capabilities and browser-specific options.
• Unable to locate driver — supported driver-location troubleshooting.
• Selenium Python 4.47.0 — Python 3.10+ requirement and package metadata.