- 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.
+ 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. +
+ ++ 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.
- 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 @@
- 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.
- 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.
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.debugger
chrome.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
sendCommandcall. This API hides request - ids and handles binding of the request with its response, hence allowing -sendCommandto report result in the callback function call. One can also use - this API in combination with the other Extension APIs. + Chrome supportschrome.debuggeronly 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.debuggercalls 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
.pdlfiles 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=9222with Chrome, the complete - protocol version it speaks is available atlocalhost:9222/json/protocol. + When Chrome runs with--remote-debugging-port=9222, the protocol schema for + that browser build is also served atlocalhost:9222/json/protocol.@@ -313,10 +370,10 @@
The endpoint is exposed as
webSocketDebuggerUrlin -/json/version. Note thebrowserin the URL, rather than -page. If Chrome was launched with--remote-debugging-port=0and - chose an open port, the browser endpoint is written to both stderr and the -DevToolsActivePortfile in browser profile folder. +/json/version. Note thebrowserpath segment in the URL rather + thanpage. When Chrome launches with--remote-debugging-port=0, + it writes the selected port and browser target path to stderr and to the +DevToolsActivePortfile 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
detachedevent. 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.detachedevent 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
-PUTmethod. Calling it withGET,POST, or any other verb fails with405 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
Hostheader. It must either be an IP address (e.g.127.0.0.1,[::1]) orlocalhost. Other hostnames trigger an immediate500 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 anOriginheader (such as from a web page), the origin must match the origins specified via--remote-allow-origins=<origin>(or @@ -798,7 +852,7 @@
fetch()orXMLHttpRequest.- - Clickjacking & Framing Protection: All + Clickjacking and framing protection: All
/json/*endpoints emitContent-Security-Policy: frame-ancestors 'none', and the discovery page (/) emitsX-Frame-Options: DENY.