# Chrome DevTools Protocol (CDP) The Chrome DevTools Protocol (CDP) is the low-level debugging protocol used to communicate with Chromium-based browsers. It allows tools to instrument, inspect, debug, and profile browsers programmatically via JSON messages over WebSocket. ## Overview CDP provides access to browser internals through a collection of domains, each offering specific functionality. It's the same protocol that powers [[Chrome DevTools]] and is used by automation tools like Puppeteer and Playwright. ## Protocol Structure ### Communication - **Transport**: WebSocket or pipe - **Format**: JSON messages - **Pattern**: Request/response + event subscriptions ### Message Types ```javascript // Request (client → browser) { "id": 1, "method": "Page.navigate", "params": { "url": "https://example.com" } } // Response (browser → client) { "id": 1, "result": { "frameId": "..." } } // Event (browser → client) { "method": "Page.loadEventFired", "params": { "timestamp": 123456.789 } } ``` ## Key Domains ### Page Control page navigation and lifecycle: - `Page.navigate` - Navigate to URL - `Page.reload` - Reload page - `Page.captureScreenshot` - Take screenshot - `Page.printToPDF` - Generate PDF - `Page.loadEventFired` - Page load event ### DOM Inspect and manipulate the DOM: - `DOM.getDocument` - Get document root - `DOM.querySelector` - Find elements - `DOM.setAttributeValue` - Modify attributes - `DOM.getOuterHTML` - Get element HTML ### Runtime Execute JavaScript: - `Runtime.evaluate` - Execute expression - `Runtime.callFunctionOn` - Call function on object - `Runtime.getProperties` - Get object properties - `Runtime.consoleAPICalled` - Console message event ### Network Monitor network activity: - `Network.enable` - Start monitoring - `Network.requestWillBeSent` - Request event - `Network.responseReceived` - Response event - `Network.setUserAgentOverride` - Change user agent - `Network.setCacheDisabled` - Disable cache ### Input Simulate user input: - `Input.dispatchMouseEvent` - Mouse events - `Input.dispatchKeyEvent` - Keyboard events - `Input.dispatchTouchEvent` - Touch events ### Debugger JavaScript debugging: - `Debugger.enable` - Enable debugger - `Debugger.setBreakpoint` - Set breakpoint - `Debugger.pause` - Pause execution - `Debugger.stepOver` - Step over ### Performance Collect performance metrics: - `Performance.enable` - Start collecting - `Performance.getMetrics` - Get current metrics ### Browser Browser-level operations: - `Browser.getVersion` - Get browser version - `Browser.close` - Close browser - `Target.createTarget` - Open new tab ## Connecting to CDP ### Endpoints When Chrome runs with `--remote-debugging-port=9222`: | Endpoint | Description | |----------|-------------| | `http://localhost:9222/json/version` | Browser version info | | `http://localhost:9222/json/list` | List of debuggable targets | | `http://localhost:9222/json/new?url` | Open new tab | | `http://localhost:9222/json/close/ID` | Close tab | ### WebSocket Connection ```javascript // Get WebSocket URL from /json/list const response = await fetch('http://localhost:9222/json/list'); const targets = await response.json(); const wsUrl = targets[0].webSocketDebuggerUrl; // Connect const ws = new WebSocket(wsUrl); ws.onmessage = (event) => console.log(JSON.parse(event.data)); // Send command ws.send(JSON.stringify({ id: 1, method: 'Page.navigate', params: { url: 'https://example.com' } })); ``` ## Libraries and Tools ### JavaScript/Node.js - **Puppeteer** - High-level API by Google - **Playwright** - Cross-browser automation by Microsoft - **chrome-remote-interface** - Low-level CDP client - **chromedp** - Go library ### Python - **pyppeteer** - Puppeteer port - **playwright-python** - Playwright for Python - **pychrome** - Low-level CDP client ### Other Languages - **chromedp** (Go) - **ferrum** (Ruby) - **chromiumoxide** (Rust) ## Browser Support CDP is supported by: - Google Chrome - Chromium - Microsoft Edge (Chromium-based) - Opera (Chromium-based) - Brave Note: Firefox has partial CDP support but primarily uses its own protocol. ## Use Cases ### Browser Automation Automate web interactions for testing or scraping. ### Testing End-to-end testing with tools like Puppeteer or Playwright. ### Performance Monitoring Collect metrics and generate performance reports. ### PDF/Screenshot Generation Server-side rendering of pages to images or PDFs. ### AI Agent Browsing Enable AI assistants to interact with web pages programmatically. ### Accessibility Testing Audit pages for accessibility issues. ## Security Notes ⚠️ CDP provides full control over the browser. A connected client can: - Execute arbitrary JavaScript - Read all cookies and storage - Access page content - Capture credentials - Navigate to any URL Always secure the debug port with proper network controls. ## Related - [[Chrome DevTools]] - Visual debugging interface - [[Chrome Debug Mode]] - Running Chrome with debugging enabled - [[socat]] - Bridge connections securely - [[Puppeteer]] - Node.js automation library - [[Playwright]] - Cross-browser automation ## References - Protocol Documentation: https://chromedevtools.github.io/devtools-protocol/ - Protocol Viewer: https://chromedevtools.github.io/devtools-protocol/tot/ - Puppeteer: https://pptr.dev/ - Playwright: https://playwright.dev/ - chrome-remote-interface: https://github.com/cyrus-and/chrome-remote-interface