WebDriver Architecture

Selenium Manager runs automatically. The binary bundled in the Selenium 4 client detects the installed Chrome, works out the matching chromedriver, downloads it if the local cache lacks it, and returns the path, so the session starts with no PATH entry and no setup code.

It asks the remote end to open a WebDriver BiDi socket for that session. If the remote end supports BiDi, the capabilities it returns contain webSocketUrl again, this time as the ws:// address the client connects to.

Constructing ChromeDriver starts a local driver process, waits for it to listen on a free loopback port, then sends it a new-session request. The driver launches the browser and replies with a session id that every later command carries.

An explicitly configured executable wins. If a driver path is set on the service builder or through the webdriver.chrome.driver system property, the Selenium 4 client launches that file; only when nothing is configured does it hand resolution to the bundled Selenium Manager.

The remote end merges alwaysMatch into every firstMatch entry in order and starts the first merged set it can support. A key repeated in both is an error, and no match at all means session not created.

The remote end creates it. The client sends a new-session request, the driver opens a browser and replies with an opaque session id. The client stores it and addresses every later command to that id, one session per driver object.

A driver service you build and start yourself is yours to stop. Orphans pile up when stop() is skipped on an exception path or the JVM is killed, so pair every start() with a finally, and add a host-level sweep for the kills.

Split it by what answered. A connection failure at the driver address means nothing was listening, so no session was requested. A session-not-created error means the endpoint answered and declined. A recorded session id means startup already finished.

ChromeDriver refuses any session whose Chrome major version differs from its own. Pin both halves to one version - a Chrome for Testing build that does not auto-update plus the driver published for it - and upgrade them together.

Selenium's command protocol is strictly request-response, so every find, click and read costs a full round trip and nothing arrives unasked. Budget commands per case, keep the remote end close, and expect all waiting to be client-side polling.

Every BiDi name is module dot member. The prefix names the module that owns it, so log owns entryAdded and network owns beforeRequestSent. The same prefixes cover commands, which is how the protocol is organised.

Classic WebDriver is client-initiated request and response: the remote end only answers, never speaks first. A browser event can only be asked for afterwards, which is why Selenium 4 adds the BiDi socket.

browserName names the browser, browserVersion asks for a build, platformName asks for an operating system, and acceptInsecureCerts asks to tolerate bad certificates. Any key you leave out places no constraint at all.

A WebElement holds an opaque id the driver assigned to a node plus the session that issued it. No markup, text or attributes come with it, so every method call asks the browser again over the wire.

The local end is the client library in your test process that turns method calls into commands. The remote end is the driver that receives them and controls the browser. Anything forwarding between the two is an intermediary node.

ChromeOptions is Selenium's typed builder for how a Chrome session starts: launch switches, preferences, extensions and the browser binary. It takes effect only when you pass that instance to the ChromeDriver constructor.

A ChromeDriverService is Selenium's handle on the chromedriver executable. It builds the command line, starts that process, and knows the local HTTP address the Java client sends its WebDriver commands to.

close() shuts only the browser window the driver is focused on and leaves the session running. quit() ends the whole session: every window it owns closes, the browser exits, and the driver process is stopped.

It means the ChromeDriver executable and the Chrome it launched are on different major versions. ChromeDriver drives one Chrome major only, so it rejects the new-session request before any page is loaded.

WebDriver BiDi is subscription-based. Connecting to the socket only establishes the channel; the remote end pushes nothing until the client sends session.subscribe naming the events or modules it wants.

Find Element returns a JSON object with one fixed key, element-6066-11e4-a52e-4f735466cecf, holding an opaque id the driver assigned to that node. The client wraps that id in a WebElement; no markup travels back.

A POST to /session creates a session and returns its id, every later command is addressed under /session/{session id}/, and a DELETE on that path ends it. The id is a path segment; the remote end holds all the state.

Headless is a browser switch, not a Selenium setting. Build a ChromeOptions, call addArguments with --headless=new, and pass that object to the ChromeDriver constructor. Selenium 4 removed the setHeadless convenience toggle.

A launch argument is a command-line switch handed to the browser process at startup; a preference is a setting written into the profile that session runs with. Chrome takes preferences as a map through setExperimentalOption; Firefox has addPreference.

Selenium's driver-service builder picks a port that is free at build time, so every service gets a different one. Call usingPort(9515) to pin a fixed port, or usingAnyFreePort() to state the default choice explicitly.

The driver executable listens on loopback and rejects non-local clients by default, because anyone who can reach it can drive a browser on that machine. ChromeDriver's --allowed-ips, and geckodriver's --host with --allow-hosts, open it deliberately.

Give Selenium Manager a driver it already has. Set SE_OFFLINE so it never attempts a download, pre-place the matching driver under the folder named by SE_CACHE_PATH, or configure an explicit driver executable so it is never consulted.

WebDriver BiDi is a W3C-specified channel that Chromium browsers and Firefox both speak, so one subscription covers the whole matrix. The DevTools bridge is Chromium-only and pinned to browser versions.

The driver looks the opaque id up in its per-browsing-context element cache, then checks two things about the node: that its document is still the active one, and that the node is still attached to that document.