Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 35 ยท Selenium 4 Features

DevTools Protocol and BiDi

Use Chrome DevTools Protocol commands and WebDriver BiDi events from Selenium: capture console logs, intercept network calls, emulate devices and geolocation.

The classic WebDriver protocol is a polite conversation: the script sends a command, the browser answers, and nothing else happens until the next command. That is enough to click and type, but real pages do much more behind your back. They log errors to the console, fire network requests, ask for your location and adapt to the device size. Selenium 4 gives you two ways to reach these hidden parts: the Chrome DevTools Protocol (CDP) on Chromium browsers, and the newer, standardized WebDriver BiDi. This lesson explains both, shows typical uses and builds a small event bus to make the idea of "the browser pushes events to you" concrete.

You cannot run browsers on this site, so the Selenium and CDP code below is read-only. Command names such as Emulation.setGeolocationOverride are real CDP commands, but BiDi and DevTools helper APIs change between Selenium versions, so check the documentation of your version before copying them. The runnable examples are stand-ins: an event bus and a request interceptor in plain JavaScript.

Two ways past the classic protocol

CDP Chromium only. Very powerful, not a standard.
BiDi A W3C standard. Events flow both ways.

CDP is available today; BiDi is where the standard is heading.

1 / 2

Commands versus events

A command is something you ask the browser to do and wait for the answer: "navigate here", "find this element". An event is something the browser tells you on its own: "a request just started", "the page logged a warning". Classic WebDriver only has commands, so to learn about an event you had to poll or inspect the page afterward.

CDP and BiDi both run over a WebSocket, which keeps one connection open so either side can send messages at any time. You tell the browser which kinds of events interest you (this is often called enabling a domain), and the browser starts pushing them. Your script registers a listener, a function that runs when an event of that kind arrives.

sequenceDiagram
  participant S as Test script
  participant B as Browser
  S->>B: Network.enable (command)
  B-->>S: ok
  S->>B: navigate to page (command)
  B-->>S: Network.requestWillBeSent (event)
  B-->>S: Network.responseReceived (event)
  B-->>S: page loaded (event)

Commands get one answer each; after Network.enable, the browser keeps pushing events.

Sending a raw CDP command

On Chromium based drivers (Chrome and Edge), the Python bindings expose execute_cdp_cmd, which sends any CDP command by name with a dictionary of parameters. Here is how to pretend to be in Berlin, so a "stores near you" feature can be tested without traveling:

Python
# read-only
driver.execute_cdp_cmd("Emulation.setGeolocationOverride", {
    "latitude": 52.52,
    "longitude": 13.405,
    "accuracy": 100,
})
driver.get("https://example.test/stores")

The page may still ask for the location permission, so grant it ahead of time in a browser profile or option, or the permission prompt will block the real API. Device emulation works the same way. This command makes the viewport behave like a phone:

Python
# read-only
driver.execute_cdp_cmd("Emulation.setDeviceMetricsOverride", {
    "width": 390,
    "height": 844,
    "deviceScaleFactor": 3,
    "mobile": True,
})

In Java, Selenium offers a typed wrapper: you cast the driver to HasDevTools, get a DevTools object, open a session and send command objects from generated classes (for example Emulation.setGeolocationOverride(...)). The Java and Python styles differ, but the CDP command names and parameters are the same.

CDP is not part of any standard. Chrome can change or remove commands, and the CDP version must roughly match the browser version. Selenium's Java bindings ship wrappers for a few recent browser versions, so a very new browser sometimes needs a newer Selenium release. Treat CDP as a sharp tool for Chromium only, and keep tests that depend on it in a clearly marked place.

Network interception

Tests of error handling are hard when the real server behaves well. With network access you can make the browser see a failure on purpose: block an analytics script that slows tests down, add a header, or answer one request with a fake response. Through CDP you can add headers for every request with Network.setExtraHTTPHeaders:

Python
# read-only
import base64

driver.execute_cdp_cmd("Network.enable", {})
token = base64.b64encode(b"tester:secret").decode()
driver.execute_cdp_cmd("Network.setExtraHTTPHeaders", {
    "headers": {"Authorization": "Basic " + token}
})
driver.get("https://staging.example.test/private")

That is one way to get past basic authentication (the browser pop-up asking for a user name and password, which Selenium cannot click because it is not part of the page). Selenium 4's Java bindings also have a helper for it, HasAuthentication, where you register credentials for a matching host. Use test accounts only, never real credentials in code (see Test Data and Configuration).

For blocking and mocking, the Java bindings offer a NetworkInterceptor where you describe which requests to match and what response to return. In plain CDP it is the Fetch domain: Fetch.enable with URL patterns, then for each Fetch.requestPaused event you answer with Fetch.continueRequest, Fetch.failRequest or Fetch.fulfillRequest. The stand-in below models exactly that handshake.

Console logs

When a button silently does nothing, the reason is often an error in the browser console. Chromium drivers can return console messages with driver.get_log("browser") in many bindings. It is a legacy log interface and its support varies, so a more robust route is listening to console events through CDP or BiDi. In Selenium Java, the BiDi LogInspector class registers a callback for console entries when the session was started with BiDi enabled (the webSocketUrl capability set to true). A good test suite fails when unexpected severe errors appear in the console, which finds broken pages even when every click succeeded.

Here is the event bus stand-in. It models the idea of one connection carrying events from several domains, listeners per event name and the "enable first" rule.

JS A tiny event bus like CDP and BiDi

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice what the first line proves: events that happen before you enable a domain are gone. In real tests, set up listeners and enable domains before you open the page, or you will miss the very errors you wanted to catch.

BiDi in practice

WebDriver BiDi is the standard's answer to CDP. It defines modules such as log, network, script and browsingContext, and the same WebSocket carries both commands and events. The goal is that the features of this lesson work in any compliant browser, not only Chromium. Today the picture is uneven: Firefox and Chromium implement large parts, the client libraries expose different amounts, and some helper names are still labelled experimental. A reasonable plan is: use the high level Selenium helper if your version has one, drop down to raw CDP on Chromium only when you must, and keep an eye on release notes as BiDi support grows.

Intercepting a request: a stand-in

The second stand-in implements the handshake from the Fetch domain: each outgoing request is "paused", a rule decides to continue, fail or fulfill it with a fake response, and the page then receives the result.

JS A request interceptor with rules

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With real Selenium the interception happens inside the browser, but the decision logic is exactly this: match, then continue, fail or fulfill. Because the second rule (fulfill) comes before the third (continue), order matters, just as in real interceptors.

When to use these tools

  • Do use network control to make rare conditions repeatable: empty lists, server errors, slow responses.
  • Do capture console errors and fail tests on unexpected ones.
  • Do use emulation for location, language and screen size when the feature depends on them.
  • Do not replace the real user flow in every test with mocked responses; keep some end-to-end tests that hit a real backend.
  • Do not depend on CDP in tests that must run in every browser. Isolate them and mark them as Chromium only.

Next you can look at how to configure the browser itself in Headless Mode and Browser Options, where the options that grant permissions and set profiles live.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main difference between a command and an event?

    You ask with a command and get one answer. Events arrive on their own after you enable the relevant domain.
  2. 2. Why does the event bus example miss the early console message?

    Events are only pushed after you enable their domain, so listeners and enabling must happen before the page does its work.
  3. 3. Which statement about CDP is true?

    CDP is Chromium's own protocol. It is powerful but browser specific, and commands can change between versions.
  4. 4. What is WebDriver BiDi?

    BiDi is the standardized protocol that carries commands and events over a WebSocket, aiming to work across browsers.
  5. 5. You want to test the screen your shop shows when the product API returns an empty list. What is a good approach?

    Fulfilling the request with a fake response makes the rare state repeatable without touching real data.

Summary

  • CDP (Chromium only) and WebDriver BiDi (a standard) let scripts reach the console, network, emulation and more over a WebSocket.
  • Commands get one answer; events are pushed after you enable a domain, so register listeners and enable domains before loading the page.
  • execute_cdp_cmd sends raw CDP commands in Python; Java offers typed DevTools wrappers and BiDi helpers such as LogInspector.
  • Interception follows a match then continue, fail or fulfill pattern; use it to make rare conditions repeatable, not to replace all end-to-end tests.
  • Keep Chromium specific code isolated and check the documentation of your Selenium version, because helper APIs change.

Next: Headless Mode and Browser Options