From 5a5d14120c93ad0b7d782eb68508487fde8e6e07 Mon Sep 17 00:00:00 2001 From: Yang Guo Date: Mon, 28 Sep 2026 11:42:33 +0200 Subject: [PATCH] docs: update CDP overview, scope, and HTTP endpoint documentation --- src/index.html | 278 +++++++++++++++++++++++++++++-------------------- 1 file changed, 166 insertions(+), 112 deletions(-) diff --git a/src/index.html b/src/index.html index 36a285015..967f7c146 100644 --- a/src/index.html +++ b/src/index.html @@ -92,65 +92,99 @@

Chrome DevTools Protocol

- The Chrome DevTools Protocol allows for tools to instrument, inspect, debug and - profile Chromium, Chrome and other Blink-based browsers. Many existing projects - currently use the - protocol. The - Chrome DevTools - uses this protocol and the team maintains its API. + The Chrome DevTools Protocol (CDP) is a JSON-based protocol that connects debug and + automation targets (such as browsing contexts and workers) with trusted debug and + automation clients. It allows tools to instrument, inspect, debug, and profile Chromium, + Chrome, and other Blink-based browsers.

- Instrumentation is divided into a number of domains (DOM, Debugger, Network, etc.). Each - domain defines a number of commands it supports and events it generates. Both commands and - events are serialized JSON objects of a fixed structure. + Instrumentation is divided into domains (DOM, Debugger, + Network, etc.). Each domain defines supported commands and generated events. + Both commands and events are serialized JSON objects of a fixed structure.

-

Protocol API Docs #

+

+ Scope and support # +

+ +

+ CDP exposes a wide range of high-privilege capabilities, so protocol clients are assumed + to be trusted. CDP is not a public or supported API for Chrome, and it does not guarantee + backwards compatibility. Syntax and semantics may change without notice based on + Chromium's requirements and Chrome's product needs. +

+ +

+ Direct use of CDP by third-party applications is unsupported. We only support official + Chrome products built on CDP: +

+ +

- The latest (tip-of-tree) protocol — It + Third-party tools that automate Chrome should use supported products such as Chrome + DevTools for agents, Puppeteer, or ChromeDriver rather than connecting to CDP directly. +

+ +

Protocol API docs #

+ +

+ The latest (tip-of-tree) protocol — Tracks the changes frequentlylatest protocol definitions - and can break at any time. However it captures the full capabilities of the Protocol, - whereas the stable release is a subset. There is no backwards compatibility support - guaranteed. + in Chromium. It captures the full capabilities of the protocol, changes frequently, and + can break at any time. Backwards compatibility is not guaranteed.

v8-inspector protocol — Enables debugging & profilingdebugging and profiling - of Node.js apps. + of Node.js applications.

- stable protocol — The stable release of the protocol, - tagged at Chrome 64. It includes a smaller subset of the complete protocol - compatibilities. + stable protocol — A historical snapshot tagged at + Chrome 64 that includes a smaller subset of protocol capabilities.

Resources #

- See - Getting Started with CDP. The + See the awesome-chrome-devtoolsCDP contribution guidelines and backend overview - page links to many of the tools in the protocol ecosystem, including protocol API - libraries in JavaScript, TypeScript, Python, Java, and Go. + and + Getting Started with CDP. For supported browser automation, use + Chrome DevTools for agents, Puppeteer, or + ChromeDriver.

- Consider subscribing to the + For questions and discussions, subscribe to the chrome-debugging-protocol @@ -161,9 +195,8 @@

Using Protocol Monitor in Chrome DevTools #

- This is especially handy to understand how the DevTools frontend makes use of the - protocol. You can view all requests/responses and methods as they happen in the Protocol - Monitor panel in DevTools. + Protocol Monitor helps you understand how the DevTools frontend uses the protocol. You can + view all requests, responses, and events as they happen in the Protocol Monitor panel.

@@ -178,27 +211,25 @@

- Click the gear icon in the top-right of the DevTools to open the Settings panel. - Select Experiments on the left of settings. Turn on "Protocol Monitor", then close - and reopen DevTools. Now click the ⋮ menu icon, choose More Tools and then select + Click the gear icon in the top-right of DevTools to open Settings. Select + Experiments on the left, turn on "Protocol Monitor", then close and reopen + DevTools. Click the ⋮ menu icon, choose More tools, and select Protocol monitor.

- You can also send commands using Protocol Monitor. If the command does not require any - parameters, type the command into the prompt at the bottom of the Protocol Monitor panel - and press Enter, for example, Page.captureScreenshot. If the command requires - parameters, provide them as JSON, for example, - {"cmd":"Page.captureScreenshot","args":{"format": "jpeg"}}. + You can also send commands from Protocol Monitor. If a command requires no parameters, + type it into the prompt at the bottom of the panel and press Enter (for example, + Page.captureScreenshot). If a command requires parameters, provide them as + JSON (for example, {"cmd":"Page.captureScreenshot","args":{"format": "jpeg"}} + ).

- By clicking on the icon next to the command input (in Chrome 117+), you can open the - command editor. After you select a CDP command, the editor creates a structured form based - on the protocol definitions that allows you to edit parameters, and view their - documentation and types. Send the commands by clicking on the send button or using - Ctrl + Enter. Use the context menu in the list of previously sent commands to - open one of them in the editor. + Click the icon next to the command input to open the command editor. After you select a + CDP command, the editor generates a structured form from the protocol definitions so you + can edit parameters and inspect their documentation and types. Send the command by + clicking the send button or pressing Ctrl + Enter.

@@ -214,9 +245,8 @@

Alternatively, you can execute commands from the DevTools console. First, - open devtools-on-devtools, then - within the inner DevTools window, use Main.MainImpl.sendOverProtocol() in the - console: + open DevTools on DevTools, then + call Main.MainImpl.sendOverProtocol() in the inner console: 

@@ -234,58 +264,86 @@ 

           DevTools protocol via Chrome extension #
         

         

-          To allow chrome extensions to interact with the protocol, we introduced
+          The
           chrome.debuggerchrome.debugger
+          extension API exposes the CDP JSON message transport to Chrome extensions. Extensions must
+          request the
+          "debugger"
-          extension API that exposes this JSON message transport interface. As a result, you can not
-          only attach to the remotely running Chrome instance, but also instrument it from its own
-          extension.
+          permission in their manifest.
         

 
         

-          Chrome Debugger Extension API provides a higher level API where command domain, name and
-          body are provided explicitly in the sendCommand call. This API hides request
-          ids and handles binding of the request with its response, hence allowing
-          sendCommand to report result in the callback function call. One can also use
-          this API in combination with the other Extension APIs.
+          Chrome supports chrome.debugger only on a best-effort basis for
+          developer-facing debugging extensions. This includes extensions that add a DevTools panel
+          with developer functionality. Non-debugger use cases and extensions aimed at end users
+          rather than developers are unsupported.
         

 
         

-          If you are developing a Web-based IDE, you should implement an extension that exposes
-          debugging capabilities to your page and your IDE will be able to open pages with the
-          target application, set breakpoints there, evaluate expressions in console, live edit
-          JavaScript and CSS, display live DOM, network interaction and any other aspect that
-          Developer Tools is instrumenting today.
+          Because CDP exposes high-privilege capabilities, the backend enforces additional access
+          controls on chrome.debugger calls to prevent extensions from accessing the
+          file system or escaping the browser sandbox. As with direct CDP connections, protocol
+          commands and events may change without notice.
         

 
+        

+          Frequently asked questions #
+        

+
+        

+          Is CDP a public or supported API for third-party products?
+          #
+        

         

-          Opening embedded Developer Tools will terminate the remote connection and thus detach the
-          extension.
+          TL;DR: No. CDP is not a public or supported API, and we do not guarantee backwards
+          compatibility.
+        

+        

+          While direct use by third parties has been tolerated, it is unsupported and may break
+          without notice when protocol syntax or semantics change. Third-party tools that automate
+          Chrome should connect indirectly through supported products such as Chrome DevTools for
+          agents, Puppeteer, or ChromeDriver.
         

 
-        

-          Frequently Asked Questions #
-        

+        

+          How are feature requests and open-source contributions handled?
+          #
+        

+        

+          TL;DR: We only accept changes motivated by our supported products, security improvements,
+          removal of outdated functionality, or Chrome architectural changes.
+        

+        

+          Changes to CDP must be approved by CDP owners, meet high technical design standards, and
+          serve web developer debugging or testing use cases. Only in exceptional cases do we accept
+          additions to automate Chrome's UI. See the
+          contribution guidelines
+          for details.
+        

 
         

           How is the protocol defined?
           #
         

         

-          The canonical protocol definitions live in the Chromium source tree: (browser_protocol.pdl
           and
           js_protocol.pdl). They are maintained manually by the DevTools engineering team. The declarative
-          protocol definitions are used across tools; for instance, a binding layer is created
-          within Chromium for the Chrome DevTools to interact with, and separately bindings
-          generated for
+          >) and are maintained by the DevTools team. These declarative definitions generate C++
+          bindings in Chromium for Chrome DevTools and
           Chrome Headless’s C++ interfaceChrome Headless.
         

 
@@ -294,17 +352,16 @@ 

         

 
         

-          These canonical .pdl files are mirrored on GitHub
-          in the devtools-protocol repo
-          where JSON versions, TypeScript definitions and closure typedefs are generated. It's
-          published regularly to NPM.
+          The canonical .pdl files are mirrored in the
+          devtools-protocol
+          GitHub repository, which generates JSON schemas, TypeScript definitions, and Closure
+          typedefs and publishes them
+          to npm.
         

 
         

-          Also, if you've set --remote-debugging-port=9222 with Chrome, the complete
-          protocol version it speaks is available at localhost:9222/json/protocol.
+          When Chrome runs with --remote-debugging-port=9222, the protocol schema for
+          that browser build is also served at localhost:9222/json/protocol.
         

 
         

@@ -313,10 +370,10 @@ 

         

         

           The endpoint is exposed as webSocketDebuggerUrl in
-          /json/version. Note the browser in the URL, rather than
-          page. If Chrome was launched with --remote-debugging-port=0 and
-          chose an open port, the browser endpoint is written to both stderr and the
-          DevToolsActivePort file in browser profile folder.
+          /json/version. Note the browser path segment in the URL rather
+          than page. When Chrome launches with --remote-debugging-port=0,
+          it writes the selected port and browser target path to stderr and to the
+          DevToolsActivePort file in the profile directory.
         

 
         

@@ -324,30 +381,27 @@ 

           #
         

         

-          Chrome 63 introduced support for multiple clients. See
+          TL;DR: Yes. Chrome 63 introduced support for
           this article
-          for details.
+            >multiple simultaneous clients.
         

 
         

-          Upon disconnection, the outgoing client will receive a detached event. For
-          example:
-          {"method":"Inspector.detached","params":{"reason":"replaced_with_devtools"}}.
-          After disconnection, some apps have chosen to pause their state and offer a reconnect
-          button.
+          When a session is disconnected, the client receives an
+          Inspector.detached event with the disconnection reason, for example:
+          {"method":"Inspector.detached","params":{"reason":"target_closed"}}.
         

 
         

-          HTTP Endpoints #
+          HTTP endpoints #
         

         

-          When Chromium or Chrome is launched with
+          When Chromium or Chrome launches with
           --remote-debugging-port=<port> (for example,
-          --remote-debugging-port=9222), it starts an internal HTTP server that exposes
-          REST endpoints and WebSocket connections for target discovery, browser lifecycle
-          management, and DevTools Protocol communication.
+          --remote-debugging-port=9222), it starts a local HTTP server that exposes
+          REST endpoints and WebSocket connections for target discovery, lifecycle management, and
+          CDP communication.
         

 
         

@@ -489,7 +543,7 @@ 

           activity time.
         

 
-        
Query Parameters:

+        
Query parameters:

         
    
           
  • 
             for_tab (optional flag): When present (e.g.
@@ -523,7 +577,7 @@ 
    
           its target descriptor.
         
    
         
    
-          Method Requirement: This endpoint
+          Method requirement: This endpoint
           strictly requires the PUT method. Calling it with
           GET, POST, or any other verb fails with
           405 Method Not Allowed (
             verb.").
         
    
-        
    Query Parameters:
    
+        
    Query parameters:
    
         
      
           
    • 
             The query component before any & is parsed and URL-unescaped as the
@@ -583,7 +637,7 @@ 
      
         
      
 
         
      
-          Target Descriptor Object
+          Target descriptor object
           #
         
      
         
      
@@ -661,7 +715,7 @@ 
      
         

 
         

-          Target Types
+          Target types
           #
         

         

@@ -770,20 +824,20 @@ 

         

 
         

-          Security & Origin Restrictions
+          Security and origin restrictions
           #
         

         
    
           
  • 
-            Host Header Validation: To mitigate DNS rebinding attacks, the server
+            Host header validation: To mitigate DNS rebinding attacks, the server
             validates the incoming HTTP Host header. It must either be an IP address
             (e.g. 127.0.0.1, [::1]) or localhost. Other
             hostnames trigger an immediate 500 Internal Server Error ("Host header is specified and is not an IP address or localhost.""Host header is specified and is not an IP address or localhost.").
           
    • 
           
  • 
-            WebSocket Origin Verification (--remote-allow-origins):
+            WebSocket origin verification (--remote-allow-origins):
             When a WebSocket handshake includes an Origin header (such as from a web
             page), the origin must match the origins specified via
             --remote-allow-origins=<origin> (or
@@ -798,7 +852,7 @@ 
    
             fetch() or XMLHttpRequest.
           
    • 
           
  • 
-            Clickjacking & Framing Protection: All
+            Clickjacking and framing protection: All
             /json/* endpoints emit
             Content-Security-Policy: frame-ancestors 'none', and the discovery page
             (/) emits X-Frame-Options: DENY.