WebDriver BiDi: Events, Network, Logs, Script, and Bidirectional Control: Core Concepts and Mental Model

1. Why classic WebDriver needs a companion channel

A command such as find_element() or click() has a clear request and response. Console messages, network requests, JavaScript exceptions, prompt events, and navigation events arrive whenever the browser produces them. Polling repeatedly can miss short-lived events, adds latency, and couples tests to timing guesses. BiDi gives the browser a standards-based path to push subscribed events back to the client.

2. Mental model: classic commands plus bidirectional events

flowchart TD
 T[Test runner] -->|Classic command| D[WebDriver / Grid]
 D -->|Command response| T
 D <-->|BiDi WebSocket| B[Browser]
 B -->|log / network / script events| T
 T -->|subscribe / unsubscribe| B
 B --> A[AUT]
 A -->|console / fetch / navigation| B
 T --> E[Correlated evidence]

The classic path remains synchronous request/response. When BiDi is enabled, the negotiated session can also expose a WebSocket URL. Selenium layers user-facing domain objects such as driver.script, driver.network, and driver.browsing_context on that channel. A subscription tells the browser which event family matters. A callback receives matching events until the handler is removed or the session ends.

3. Objects and state stores

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

4. Read-only preflight before enabling listeners

The following example makes the Read-only preflight before enabling listeners behavior concrete. Read it with the stated assumptions, then compare its observable output or state changes with the explanation that follows.

import selenium
from selenium import webdriver

options = webdriver.ChromeOptions()
options.enable_bidi = True

driver = webdriver.Chrome(options=options)
try:
    caps = driver.capabilities
    print("selenium", selenium.__version__)
    print("session", driver.session_id)
    print("browser", caps.get("browserName"), caps.get("browserVersion"))
    print("platform", caps.get("platformName"))
    print("webSocketUrl", caps.get("webSocketUrl"))
    print("classic_handle", driver.current_window_handle)
finally:
    driver.quit()

options.enable_bidi = True asks Selenium to negotiate BiDi. The returned webSocketUrl capability proves whether that session actually exposes the transport. Record browser/binding versions and the negotiated value rather than assuming support from the browser name alone.

5. Events and command domains

BiDi is organized into domains. Logging use cases are surfaced by Selenium through the script namespace, network interception/observation through network, and browsing-context control through browsing_context. The protocol itself contains lower-level commands and event types, but Selenium explicitly encourages high-level use-case APIs where available.

6. Subscription lifecycle is resource lifecycle

An event handler is not a free-standing callback. It is session-scoped state. Add it before the triggering action, preserve the returned handler/subscription identifier, and remove it in cleanup. If a fixture reuses a browser session, an unremoved handler can fire in later tests and create duplicate evidence.

events = []
handler_id = driver.script.add_console_message_handler(events.append)
try:
    # trigger only after the handler exists
    pass
finally:
    driver.script.remove_console_message_handler(handler_id)

7. Browsing context is not merely “the current tab”

BiDi event APIs can scope subscriptions to browsing contexts. A context identifier has protocol meaning: it identifies a context in the BiDi context tree. Classic WebDriver window handles identify top-level contexts for classic commands. Current Selenium may bridge these concepts in convenient APIs, but production code should still label the identifier type explicitly instead of passing opaque strings between layers and hoping they are interchangeable.

8. High-level APIs versus low-level/internal classes

The following table organizes the key choices and evidence for High-level APIs versus low-level/internal classes. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

9. BiDi versus CDP

Chrome DevTools Protocol is a Chromium protocol. Selenium has historically exposed CDP to bridge gaps while WebDriver BiDi matured. Current Selenium documentation describes CDP support as temporary, and Selenium 4.47 blocks Firefox CDP access in Python. A test that calls Chromium CDP and then labels itself “cross-browser BiDi” is architecturally incorrect.

10. Trust boundaries and privacy

BiDi can reveal rich telemetry. Console messages may contain tokens; network handlers can see URLs, headers, cookies, and possibly bodies; remote WebSocket endpoints are session infrastructure. Use synthetic data in training, redact before persistence, minimize subscriptions, and never expose public Grid/BiDi endpoints. Event richness increases privacy responsibility.

11. DevOps connection: observability with version discipline

BiDi can turn opaque CI failures into event-rich incidents, but only if the pipeline records the exact Selenium binding, browser version, returned capabilities, selected domains, handler lifecycle, and any fallback used. A green test produced after silently disabling unsupported evidence is not equivalent to a fully observed run.

12. Lesson summary

• Classic WebDriver issues commands; BiDi adds asynchronous browser-to-client events and bidirectional control.
• Enablement is negotiated per session and should be proven by returned capability state.
• Subscriptions are resources that must be created before the trigger and removed deterministically.
• Browsing-context identifiers, classic handles, domains, and WebSocket endpoints are distinct concepts.
• Prefer high-level Selenium BiDi APIs; isolate low-level version-sensitive code.
• CDP is browser-specific and temporary, not cross-browser BiDi.

Knowledge check

Official references and version notes

• Selenium 4.47 release notes — current stable client/Grid baseline and BiDi changes.
• WebDriver BiDi overview — high-level Selenium direction and CDP relationship.
• W3C-compliant BiDirectional API — cross-browser WebSocket event model and domains.
• BiDi logging features — console and JavaScript error handlers.
• BiDi network features — request/response/auth handler concepts.
• BiDi script features — high-level script namespace.
• Python Options API — enable_bidi.
• Selenium Python API 4.47 — Python 3.10+ and current binding surface.
• Selenium Grid — remote sessions and the next chapter boundary.