Selenium Ecosystem, Installation, and First WebDriver Session: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

flowchart TD
  E["Preserve first error"] --> V["Binding + Python version"]
  V --> M["Manager / driver resolution"]
  M --> B["Browser availability + version"]
  B --> S["Session + capabilities"]
  S --> T["Loopback target"]
  T --> C["Command / locator / app behavior"]
  C --> F["Smallest correction + controlled rerun"]

If the session constructor fails, there is no DOM, locator, or application interaction to debug yet. If the session starts and the loopback page is unreachable, the driver/browser layer is probably not the first suspect. Keep the sequence aligned with what was actually created.

2. Common first-session failure classes

The following table organizes the key choices and evidence for Common first-session failure classes. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

3. Intentionally broken example: explicit missing driver

This failure is reversible because it does not alter PATH, the Manager cache, or a real executable. Save as broken_driver.py:

from selenium import webdriver
from selenium.common.exceptions import WebDriverException

service = webdriver.ChromeService(executable_path="./does-not-exist/chromedriver")
try:
    webdriver.Chrome(service=service)
except WebDriverException as exc:
    print(type(exc).__name__)
    print(str(exc).splitlines()[0])

The key design choice is the explicit Service. You told Selenium to use a specific nonexistent executable, so the failure belongs to the driver-service configuration before the browser session exists. Fix it by removing the manual override:

from selenium import webdriver

driver = None
try:
    driver = webdriver.Chrome()  # default Manager path
    print(driver.capabilities.get("browserVersion"))
finally:
    if driver is not None:
        driver.quit()

Do not “fix” this example by copying a random driver binary into the repository. Let the selected management strategy own the executable deliberately.

4. Stale driver on PATH: diagnose without deleting first

Current Selenium Manager can warn about an incompatible driver discovered on PATH. Before deleting anything, capture the browser version, the driver version reported in the warning, and the path. In a disposable shell you can ask Manager to ignore PATH drivers using the current SE_SKIP_DRIVER_IN_PATH=true setting and rerun the smallest session. If that succeeds, you have evidence that PATH selection mattered.

SE_DEBUG=true SE_SKIP_DRIVER_IN_PATH=true SE_AVOID_STATS=true python session.py 2> manager-skip-path.log

After confirming cause, fix the machine through its normal package/tooling policy: update/remove the stale manually managed driver, or keep the PATH-skip policy if that is an approved environment contract. Avoid ad-hoc deletion on shared build agents.

5. Corporate proxy and offline behavior

Selenium Manager may need browser-vendor metadata and downloads on a cold cache. Current Manager supports an HTTP proxy setting, timeout, offline mode, mirror URLs, and a configurable cache path. Treat proxy credentials as secrets. Never paste a real user:password@proxy into a course file, CI log, or ticket.

# Architecture example only; this host is intentionally invalid.
SE_PROXY=proxy.example.invalid:8080 SE_DEBUG=true python session.py

# Offline is useful only when required assets/metadata are already available locally.
SE_OFFLINE=true python session.py

A TLS or proxy failure is not a reason to add insecure browser flags or globally disable certificate validation. Establish the approved egress trust path or pre-provision/cache the required assets.

6. Session leaks after exceptions

The most common beginner leak is code that calls quit() only at the happy-path end. Any exception before that line can skip cleanup. Prefer try/finally in small scripts and framework fixtures with guaranteed teardown in real suites.

from selenium import webdriver

driver = webdriver.Chrome()
try:
    driver.get("http://127.0.0.1:8008/")
    assert driver.title == "Selenium Chapter 02 Fixture"
    raise RuntimeError("synthetic failure after session creation")
finally:
    driver.quit()

The synthetic exception demonstrates that teardown still runs. Do not intentionally leave orphan browsers as a teaching technique.

7. Local success does not prove CI portability

A developer workstation may have a browser already installed, interactive display support, a warm Manager cache, broad network egress, user fonts, and generous memory. A CI runner may have none of those. Preserve a compact environment record in both places: Python/Selenium versions, OS/architecture, browser/driver versions, browser options, whether the browser was system or managed, Manager/cache/proxy policy, and relevant resource/container context.

If CI fails before a session ID exists, do not add test retries. Retries repeat the same environment defect. Fix the missing browser/driver/runtime/display/container dependency and rerun the smallest session probe.

8. Production practices for installation diagnostics

• Pin and review the binding dependency.
• Record negotiated capabilities on every CI run.
• Keep driver-management ownership explicit: Manager, approved image, or approved manual service.
• Use per-job workspaces/profiles instead of personal browser profiles.
• Sanitize Manager/service logs before sharing.
• Do not expose Grid or driver service ports publicly.
• Do not treat blanket retries or browser restarts as root-cause fixes.
• Do not clear the entire Manager cache as the first response; preserve evidence and scope the issue first.

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.