TheChrome DevTools Protocol allows for tools to instrument, inspect, debug and profile Chromium, Chrome and other Blink-based browsers.Many existing projectscurrently use the protocol.TheChrome DevTools uses this protocol and the team maintains its API.

Instrumentation is divided into a number of domains (DOM, Debugger, Networketc.). Each domain defines a number of commands it supports and events itgenerates. Both commands and events are serialized JSON objects of a fixedstructure.

Protocol API Docs

The latest (tip-of-tree) protocol (tot) —Itchanges frequentlyand 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.

v8-inspector protocol (v8) —Enablesdebugging & profilingof Node.js apps.

stable 1.3 protocol (1-3) —The stable release of the protocol, tagged at Chrome 64. It includes a smaller subset of the complete protocol compatibilities.

Resources

SeeGetting Started with CDP. Theawesome-chrome-devtools page links to many of the tools in the protocol ecosystem, including protocol API libraries in JavaScript, TypeScript, Python, Java, and Go.

Consider subscribing to thechrome-debugging-protocol mailing list.

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 Monitorpanel in DevTools.

Click the gear icon in the top-right of the DevTools to open theSettings panel.SelectExperiments on the left of settings. Turn on "Protocol Monitor", then close and reopen DevTools.Now click the ⋮ menu icon, chooseMore Tools and then selectProtocol 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"}}.

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 usingCtrl + Enter. Use the context menu in the list of previously sent commands to open one of them in the editor.

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

let Main = await import('./devtools-frontend/front_end/entrypoints/main/main.js'); // or './entrypoints/main/main.js' or './main/main.js' depending on the browser versionawait Main.MainImpl.sendOverProtocol('Emulation.setDeviceMetricsOverride', {  mobile: true,  width: 412,  height: 732,  deviceScaleFactor: 2.625,});const data = await Main.MainImpl.sendOverProtocol("Page.captureScreenshot");

DevTools protocol via Chrome extension

To allow chrome extensions to interact with the protocol, we introducedchrome.debuggerextension API that exposes this JSON messagetransport interface. As a result, you can not only attach to the remotelyrunning Chrome instance, but also instrument it from its own extension.

Chrome Debugger Extension API provides a higher level API where commanddomain, name and body are provided explicitly in thesendCommandcall. This API hides request ids and handles binding of the request with itsresponse, hence allowingsendCommand to report result in thecallback function call. One can also use this API in combination with the otherExtension APIs.

If you are developing a Web-based IDE, you should implement an extension thatexposes debugging capabilities to your page and your IDE will be able to openpages with the target application, set breakpoints there, evaluate expressionsin console, live edit JavaScript and CSS, display live DOM, network interactionand any other aspect that Developer Tools is instrumenting today.

Opening embedded Developer Tools willterminate theremote connection and thus detach the extension.

Frequently Asked Questions

How is the protocol defined?

The canonical protocol definitions live in the Chromium source tree:(browser_protocol.pdlandjs_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 forChrome Headless’s C++ interface.

Can I get the protocol as JSON?

These canonical .pdl files are mirrored on GitHubin the devtools-protocol repowhere JSON versions, TypeScript definitions and closure typedefs are generated. It's publishedregularly to NPM.

Also, if you've set--remote-debugging-port=9222 with Chrome, the complete protocol version it speaksis available atlocalhost:9222/json/protocol.

How do I access the browser target?

The endpoint is exposed aswebSocketDebuggerUrl in/json/version.Note thebrowser in the URL, rather thanpage.If Chrome was launched with--remote-debugging-port=0 and chose an open port,the browser endpoint is written to both stderr and theDevToolsActivePort file in browser profile folder.

Does the protocol support multiple simultaneous clients?

Chrome 63 introduced support for multiple clients. Seethis article for details.

Upon disconnection, the outgoing client will receive adetached event.For example:{"method":"Inspector.detached","params":{"reason":"replaced_with_devtools"}}.View theenum ofpossible reasons.(For reference: theoriginal patch).After disconnection, some apps have chosen to pause their state and offer a reconnect button.

HTTP Endpoints

If started with a remote-debugging-port, these HTTP endpoints are available on the same port.(Chromium implementation)

GET/json/version

Browser version metadata

{    "Browser": "Chrome/72.0.3601.0",    "Protocol-Version": "1.3",    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3601.0 Safari/537.36",    "V8-Version": "7.2.233",    "WebKit-Version": "537.36 (@cfede9db1d154de0468cb0538479f34c0755a0f4)",    "webSocketDebuggerUrl": "ws://localhost:9222/devtools/browser/b0b8a4fb-bb17-4359-9533-a8d9f3908bd8"}

GET/json or/json/list

A list of all available websocket targets.

[ {  "description": "",  "devtoolsFrontendUrl": "/devtools/inspector.html?ws=localhost:9222/devtools/page/DAB7FB6187B554E10B0BD18821265734",  "id": "DAB7FB6187B554E10B0BD18821265734",  "title": "Yahoo",  "type": "page",  "url": "https://www.yahoo.com/",  "webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/DAB7FB6187B554E10B0BD18821265734"} ]

GET/json/protocol/

The current devtools protocol, as JSON:

{  "domains": [      {          "domain": "Accessibility",          "experimental": true,          "dependencies": [              "DOM"          ],          "types": [              {                  "id": "AXValueType",                  "description": "Enum of possible property types.",                  "type": "string",                  "enum": [                      "boolean",                      "tristate",// ...

PUT/json/new?{url}

Opens a new tab. Responds with the websocket target data for the new tab.

GET/json/activate/{targetId}

Brings a page into the foreground (activate a tab).

For valid targets, the response is 200:"Target activated".If the target is invalid, the response is 404:"No such target id: {targetId}"

GET/json/close/{targetId}

Closes the target page identified bytargetId.

For valid targets, the response is 200:"Target is closing".If the target is invalid, the response is 404:"No such target id: {targetId}"

WebSocket/devtools/page/{targetId}

The WebSocket endpoint for the protocol.

GET/devtools/inspector.html

A copy of the DevTools frontend that ship with Chrome.