The Chrome DevTools Protocol and developer tools

Opening the tools#

Press F12, or Ctrl+Shift+I (Windows and Linux) or Cmd+Option+I (macOS), or right-click an element and choose Inspect. A panel opens beside or below the page. In Chrome, the tools are themselves a web page that talks to the page you inspect over the Chrome DevTools Protocol, so anything the panels can do, a program can do too.

The panels#

Most of this page is about two of them, Console and Network, because they are the two you will open most often when a test misbehaves.

The Console in depth#

The Console has two jobs: it shows what the page logs, and it runs what you type, in the page’s own context, with the page’s own variables.

Levels#

Every message has a level. The filter menu at the top of the panel shows or hides each level.

The browser also writes to the Console by itself, always at the Error or Warning level: an uncaught exception in a script, a promise rejected with nothing to handle it, a failed request (Failed to load resource), a mixed-content or CORS block, and a deprecation notice. For a test these are valuable: a page that renders fine but logs a red error is often the first sign of a bug.

Helpers that only exist in the Console#

The Console has a few shortcuts that are not part of the page. A script on the page cannot use them, only the prompt can.

A typical selector check takes ten seconds. Select the button in the Elements panel, then type:

$0.outerHTML                      // what exactly did I select?$$('button.primary').length       // how many elements will my selector match?$$('button.primary').map(b => b.textContent.trim())

If the length is 0 or 2, the selector is wrong for a test whatever it looks like on screen. Remember that the Console runs in the top frame by default; a selector for something inside an iframe needs the context menu at the top of the panel switched to that frame, just as automation must switch to the frame first.

Other useful calls#

console.table(array) prints an array of objects as a table, console.group and console.groupEnd indent related lines, console.time('x') with console.timeEnd('x') measures a duration, console.assert(condition, 'message') logs only when the condition is false, and console.trace() prints the call stack at that point. Tick Preserve log to keep messages across a page navigation, which is what you want while debugging a login flow.

Network and Copy as cURL#

The Network panel lists every request the page makes. Click one to see its request headers, response headers, payload and response body. The filter row narrows the list to Fetch/XHR (the API calls of a modern app, see frontends, backends and APIs), documents, scripts or images.

Right-click a request and Copy offers several forms. Copy as cURL produces a command you can paste into a terminal and run, with the method, URL, headers, cookies and body of that exact request:

curl 'https://example.com/api/items?page=2' \  -H 'accept: application/json' \  -H 'authorization: Bearer REDACTED' \  -H 'cookie: session=REDACTED' \  --compressed

Reproducing a request with curl answers a useful question: does the call work without the browser? If it does, a test may not need a browser for that step at all; if it fails, the difference between the browser’s request and yours (a header, a cookie, a token) is the thing to find. Copy as fetch gives the same request as JavaScript, and Save all as HAR writes the whole list to a file that other tools can read, as described in Network.

Where CDP comes from#

The developer tools above are a web page that is not built into the browser’s engine: they talk to the page you are inspecting over a protocol, the Chrome DevTools Protocol. They read the DOM, list network requests, set breakpoints and take screenshots by sending that protocol’s messages.

Because the protocol is just messages over a network connection, any program can be the “developer tools”. Puppeteer, Playwright and the pure CDP engine of seleniumbase-rs are such programs. The protocol belongs to Chromium (Chrome, Edge, Brave, Opera), is versioned with the browser and is not a web standard. Its definition is public (the “protocol viewer” on the Chrome DevTools site), and some of its parts are marked experimental or deprecated and do change.

Connecting#

The remote debugging port#

The tools above are a client. What they connect to is a debugging port that the browser itself opens. When the tools are built into the same browser you barely notice it, but you can start Chrome with a port and connect to it from another program, or from the DevTools of another Chrome:

chrome --remote-debugging-port=9222 --user-data-dir=/tmp/debug-profile

Then open http://127.0.0.1:9222/json/version in any browser to see the version and the WebSocket address, or open chrome://inspect in another Chrome to attach to the tabs. The messages on that connection are the ones described in The messages below.

Several clients can attach to the same tab at once, so a person can watch the panels while a program drives the page.

The messages#

There are exactly three kinds of message.

// 1. A command, client to Chrome. It has an id that the client chooses.{"id": 7, "method": "Page.navigate", "params": {"url": "https://example.com"}}// 2. The reply, Chrome to client. It repeats the id, so replies can arrive in any order.{"id": 7, "result": {"frameId": "A1B2", "loaderId": "C3D4"}}// 2b. Or, when the command fails, an error instead of a result.{"id": 7, "error": {"code": -32000, "message": "Cannot navigate to invalid URL"}}// 3. An event, Chrome to client. It has no id: nobody asked for it.{"method": "Page.loadEventFired", "params": {"timestamp": 41203.5}}

A command is a method named Domain.command plus its params. The id lets a client keep many commands in flight at once and match each reply to its caller. Events are how the browser tells the client something happened. Most events arrive only after the client turns the domain on with an enable command, such as Network.enable, so a busy page does not flood a client that did not ask.

Domains#

The protocol is split into domains, one for each part of the browser. These are the ones that matter for automation:

Targets and sessions#

A running Chrome is not one thing to talk to but many. Each tab, each cross-site iframe, each service worker and shared worker, and the browser itself is a target. To command one, the client attaches to it:

{"id": 1, "method": "Target.attachToTarget", "params": {"targetId": "T-42", "flatten": true}}// reply: {"id": 1, "result": {"sessionId": "S-9"}}// From now on, a command for that tab carries its sessionId, on the SAME WebSocket:{"id": 2, "sessionId": "S-9", "method": "Page.navigate", "params": {"url": "https://example.com"}}

With flatten: true, the sessions of all tabs share the one connection, and the sessionId field says whom a message is for or from. A session is a private conversation with one target: enabling Network in one tab does not start network events in another.

The browser also has browser contexts, the protocol’s name for what Chrome shows as an incognito window. Target.createBrowserContext makes one; targets created inside it share cookies and storage with each other and with nothing else. See Sessions, cookies and storage.

What a page load looks like#

Navigation in CDP: the reply to Page.navigate only says the navigation started. The page is loaded when the events arrive.

That is why a good client subscribes before it navigates: the load event can arrive before the reply to the command does. If a navigation fails (no network, a bad certificate), the reply carries an errorText such as net::ERR_NAME_NOT_RESOLVED. See how a page loads for what those events mean.

What a click looks like#

CDP has no “click this element” command. A click is built from smaller pieces:

A typical click. Many clients also scroll the element into view first.

Input.dispatchMouseEvent goes through the browser’s real input path, so the page sees ordinary events whose isTrusted property is true. A script that only calls element.click() produces an untrusted event, which some sites refuse.

JavaScript results come back as remote objects: Runtime.evaluate returns a description (type and value), or, for an object that cannot be copied, an objectId the client can pass to later commands such as Runtime.callFunctionOn. With returnByValue the browser copies the value into the reply.

CDP compared with WebDriver#

CDP can do things the classic WebDriver protocol cannot: pause and rewrite requests, set the time zone, emulate a phone, print to PDF, record a HAR. The price is that every higher-level behaviour (waiting for an element, scrolling before a click) is the client’s job. WebDriver BiDi is the standards-based effort to bring the event-style features to every browser.

How seleniumbase-rs uses it#

The pure CDP engine#

The pure CDP engine lives in seleniumbase_rs::sb_cdp.

The pure CDP engine and Chrome

• One connection. The client in src/sb_cdp/client.rs keeps one WebSocket for every tab. A background task reads it, completes the pending request that matches each reply id, and broadcasts everything else as an event, so commands from different tabs never block one another. A command that gets no reply is abandoned after 30 seconds.
• Launching. Browser::launch(LaunchOptions) starts Chrome with a debugging port and waits for it to publish its endpoint (20 seconds by default; startup_timeout changes that). LaunchOptionsBuilder::debugging_port fixes the port instead of letting Chrome choose.
• Tabs and contexts. Browser::default_page() returns the first tab as a Page; Browser::new_context() creates an isolated BrowserContext.
• Raw commands. Page::execute(method, params) sends any command to one tab, Browser::execute sends one to the browser itself, and Page::events() gives an Events handle for the tab’s protocol events.
• Navigation. Page::goto follows the order described above: it listens first, sends Page.navigate, reads errorText and loaderId from the reply, and waits for the load event. A change of only the #fragment has no loaderId and fires no load event, so it returns at once.
• Input. Page::mouse() and Page::keyboard() send Input.dispatchMouseEvent and Input.dispatchKeyEvent, so clicks and keystrokes are trusted events. A Locator uses them for you.
• Other domains. Interception uses Fetch (Network), Page::apply_fingerprint uses Page.addScriptToEvaluateOnNewDocument and Emulation (Detection and spoofing), and Page::emulation() exposes time zone, locale, geolocation, user agent and offline mode.

use seleniumbase_rs::sb_cdp::{Browser, LaunchOptions};let browser = Browser::launch(LaunchOptions::builder().headless(true).build()?).await?;let page = browser.default_page().await?;page.goto("example.com").await?;page.locator("h1").expect().to_contain_text("Example").await?;browser.close().await?;

use serde_json::json;let reply = page    .execute("Runtime.evaluate", json!({ "expression": "document.title", "returnByValue": true }))    .await?;println!("title = {}", reply["result"]["value"]);// For plain JavaScript there is a shortcut:let title = page.evaluate("document.title").await?;

DevTools from the command line, Rust and MCP#

The project does not draw its own tools. It starts a browser the real DevTools can reach and gives programs and AI assistants the same information.

sbrs devtools --port 9222sbrs devtools --headless --json

sbrs cdp --cmd Browser.getVersionsbrs cdp --cmd Target.getTargets

use seleniumbase_rs::sb_cdp::{Browser, LaunchOptions};let browser = Browser::launch(LaunchOptions::builder().headless(true).build()?).await?;let endpoint = browser.devtools_endpoint();println!("attach DevTools to {}", endpoint.http_url());println!("version document: {}", endpoint.version_url());

Debugging tools for MCP clients#

The MCP servers of sbrs-mcp (see MCP) offer the pieces of the panels as tools, so an assistant can look at a page the way you would:

Where to go next#