Headless Chromium & the Chrome DevTools Protocol

What is CDP

The Chrome DevTools Protocol is a JSON-RPC-style protocol exposed over WebSocket by Chromium-based browsers. It's the same wire protocol that Chrome DevTools uses internally. When you open the Elements panel, set a breakpoint, or profile a page, the frontend is sending CDP messages to the browser backend.

Anything DevTools can do, you can do programmatically. That includes navigating pages, intercepting network requests, executing JavaScript in page context, capturing screenshots, recording performance traces, setting debugger breakpoints, and injecting input events. The protocol surface is large: over 40 domains, hundreds of commands, and hundreds of events.

CDP is a browser capability, not a headless-specific feature. The protocol works identically whether the browser window is visible on screen or running headless. You can launch Chrome normally, add --remote-debugging-port=9222, and control it programmatically while watching everything happen in the UI. That's actually one of the most useful debugging setups: your script drives the browser while you observe it visually in real time.

Higher-level libraries like Puppeteer and Playwright are built on top of CDP (Playwright also supports its own protocol for Firefox/WebKit). They're convenient, but they abstract away most of the protocol's power. Understanding the raw protocol gives you access to everything the browser exposes, including things no library wraps.

Launching Chromium with CDP

The only flag you need for CDP access is --remote-debugging-port. Everything else is optional. This works in both headed mode (normal browser window) and headless mode (no UI). The protocol, the WebSocket endpoint, the available commands, and the behavior are all identical either way. The choice between headed and headless is purely about whether you want a visible window.

Headed mode (visible browser window)

This is the most useful mode for development and debugging. You can watch your script navigate, click, and interact while inspecting state programmatically at the same time.

# macOS — launch Chrome with a visible window and CDP enabled
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222

# Linux
chromium-browser --remote-debugging-port=9222

# Isolate from your normal browsing profile
chromium --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug \
  --no-first-run

Once launched, the browser window works normally. You can interact with it manually while your script also sends CDP commands. You can even open DevTools in the browser window alongside your programmatic CDP session. Both use the same protocol; they coexist without conflict.

Headless mode (no visible window)

For automation on servers, CI pipelines, containers, or anywhere you don't have (or need) a display. Chrome and Chromium have shipped --headless since 2017. The "new headless" mode (Chrome 112+) runs the full browser engine, sharing the same code path as headed mode. The old headless was a separate, stripped-down implementation that's now deprecated.

# macOS (Chrome)
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --headless=new \
  --remote-debugging-port=9222

# Linux
chromium-browser --headless=new --remote-debugging-port=9222

# Specify a user data dir to isolate sessions
chromium --headless=new \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug \
  --no-first-run \
  --disable-default-apps

Useful launch flags

Verifying the endpoint

Once Chrome is running with --remote-debugging-port=9222, it exposes a few HTTP endpoints:

# List open targets (pages, service workers, etc.)
curl -s http://localhost:9222/json/list | jq .

# Browser version info
curl -s http://localhost:9222/json/version | jq .

# Open a new tab
curl -s http://localhost:9222/json/new?http://example.com

# Close a tab by target ID
curl -s http://localhost:9222/json/close/TARGET_ID

The /json/version response includes a webSocketDebuggerUrl field. That's the WebSocket endpoint for browser-level CDP commands. Each target in /json/list has its own webSocketDebuggerUrl for page-level commands.

Your first CDP script

Raw WebSocket approach (Node.js)

No libraries. Just a WebSocket, JSON-RPC message IDs, and the CDP spec. This is the most educational way to understand what's happening.

import WebSocket from 'ws';

// Discover the WebSocket URL from the /json/version endpoint
const info = await fetch('http://localhost:9222/json/version')
  .then(r => r.json());
const ws = new WebSocket(info.webSocketDebuggerUrl);

let msgId = 0;
const pending = new Map();

function send(method, params = {}) {
  return new Promise((resolve, reject) => {
    const id = ++msgId;
    pending.set(id, { resolve, reject });
    ws.send(JSON.stringify({ id, method, params }));
  });
}

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.id && pending.has(msg.id)) {
    const { resolve, reject } = pending.get(msg.id);
    pending.delete(msg.id);
    msg.error ? reject(msg.error) : resolve(msg.result);
  } else if (msg.method) {
    // This is an event (e.g., Network.requestWillBeSent)
    console.log(`[event]`, msg.method, msg.params);
  }
});

ws.on('open', async () => {
  // Create a new target (tab)
  const { targetId } = await send('Target.createTarget', {
    url: 'about:blank'
  });

  // Attach to it to get a session for page-level commands
  const { sessionId } = await send('Target.attachToTarget', {
    targetId,
    flatten: true
  });

  // Now send commands scoped to this session
  const sendToPage = (method, params = {}) => {
    return new Promise((resolve, reject) => {
      const id = ++msgId;
      pending.set(id, { resolve, reject });
      ws.send(JSON.stringify({ id, method, params, sessionId }));
    });
  };

  await sendToPage('Page.enable');
  await sendToPage('Network.enable');

  await sendToPage('Page.navigate', {
    url: 'https://example.com'
  });

  // Wait for load, then screenshot
  await new Promise(r => setTimeout(r, 2000));

  const { data } = await sendToPage('Page.captureScreenshot', {
    format: 'png'
  });

  const fs = await import('fs');
  fs.writeFileSync('screenshot.png', Buffer.from(data, 'base64'));
  console.log('Screenshot saved.');

  ws.close();
});

The key concepts: every CDP message is JSON with an id (for request/response correlation), a method (domain.command), and params. Events arrive without an id and carry a method field. Sessions (via Target.attachToTarget with flatten: true) multiplex multiple targets over a single WebSocket.

Puppeteer

Puppeteer is the most common high-level wrapper. It manages browser launch, provides a page API, and handles CDP session management. You can still drop down to raw CDP when needed.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: 'new',
  args: ['--remote-debugging-port=9222']
});

const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle0' });

// High-level API
await page.screenshot({ path: 'screenshot.png', fullPage: true });

// Drop to raw CDP when you need something Puppeteer doesn't wrap
const cdp = await page.createCDPSession();

// Enable the Debugger domain
await cdp.send('Debugger.enable');

// Get a JS heap snapshot
await cdp.send('HeapProfiler.enable');
cdp.on('HeapProfiler.addHeapSnapshotChunk', ({ chunk }) => {
  process.stdout.write(chunk);
});
await cdp.send('HeapProfiler.takeHeapSnapshot', {
  reportProgress: false
});

await browser.close();

Playwright

Playwright has its own protocol for cross-browser support, but exposes CDP for Chromium targets.

import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: true });
const context = await browser.newContext();
const page = await context.newPage();

// Get a CDP session from any Playwright page
const cdp = await page.context().newCDPSession(page);

await cdp.send('Performance.enable');
await page.goto('https://example.com');

const { metrics } = await cdp.send('Performance.getMetrics');
console.log(metrics);

await browser.close();

Python

The pychrome library gives you a clean CDP wrapper. For async workflows, nodriver (successor to undetected-chromedriver) or the cdp package work well.

import pychrome
import base64

browser = pychrome.Browser(url="http://127.0.0.1:9222")
tab = browser.new_tab()

# Start listening for events
tab.start()
tab.call_method("Page.enable")
tab.call_method("Network.enable")

# Navigate
tab.call_method("Page.navigate", url="https://example.com")
tab.wait(3)

# Screenshot
result = tab.call_method("Page.captureScreenshot", format="png")
with open("screenshot.png", "wb") as f:
    f.write(base64.b64decode(result["data"]))

# Evaluate JS in page context
result = tab.call_method("Runtime.evaluate",
    expression="document.title")
print(result["result"]["value"])

tab.stop()
browser.close_tab(tab)

Reference script: chromium-browse

A working implementation of everything above is available as chromium-browse, installable via Homebrew from the mac-security tap. It controls any Chromium-based browser purely through raw CDP over WebSocket. No Puppeteer, no Playwright, no third-party browser engine. Just the protocol.

What the script does

1. Launches the browser in --headless=new mode with a temporary user data directory (isolated profile, no leftover state)
2. Reads a list of URLs from urls.txt, shuffles the order each round
3. For each URL: navigates via Page.navigate, waits for load, scrolls the viewport randomly using Runtime.evaluate
4. Dwells on each page for a randomized period (configurable min/max)
5. Discovers same-domain links using Runtime.evaluate to query the DOM for <a href> elements
6. Follows a random subset of those links (up to --max-depth levels deep), skipping assets like images, PDFs, fonts, and off-domain URLs
7. Cleans up the temp profile directory on exit

CDP commands used

The script uses a small but representative slice of the protocol. This is a useful reference for anyone building their own CDP automation from scratch. Every technique is transferable to Chrome, Edge, Brave, Island, or any Chromium fork. Swap the browser binary path and the rest works unchanged.

How it connects

The script follows the same pattern shown in the raw WebSocket example above:

1. Launch the browser with --remote-debugging-port=PORT and a disposable --user-data-dir
2. Poll http://localhost:PORT/json/version until the browser is ready (the CDP endpoint takes a moment to come up)
3. Connect to the webSocketDebuggerUrl from the version response
4. Send JSON-RPC messages with incrementing IDs, correlate responses by ID, and handle events by method name
5. Use Target.createTarget + Target.attachToTarget with flatten: true to scope commands to individual tabs

The Python implementation uses the websockets library for the WebSocket connection and aiohttp for the initial HTTP endpoint check. Everything else is stdlib. Total external dependencies: two packages.

Remote debugging

The debugging port isn't just for headless automation. It's a full remote debugging interface. You can attach Chrome DevTools from another machine, connect multiple clients, and debug browsers running in containers, VMs, or on mobile devices.

Over the network

Launch Chrome on the target machine binding to all interfaces:

chromium --headless=new \
  --remote-debugging-port=9222 \
  --remote-debugging-address=0.0.0.0 \
  --remote-allow-origins=*

On your workstation, open chrome://inspect in Chrome, click "Configure" next to "Discover network targets," and add TARGET_IP:9222. The remote browser's tabs will appear in the list, and you can click "inspect" to get a full DevTools window connected to the remote target.

SSH tunnel (the right way)

Keep the debugging port bound to localhost and tunnel through SSH:

# On local workstation: forward local 9222 to remote's localhost:9222
ssh -L 9222:localhost:9222 user@remote-host

# Now access DevTools at chrome://inspect targeting localhost:9222
# Or connect programmatically
curl -s http://localhost:9222/json/version

This gives you encrypted, authenticated access without exposing the port.

Docker containers

# Dockerfile
FROM chromedp/headless-shell:latest
EXPOSE 9222
ENTRYPOINT ["/headless-shell/headless-shell", \
  "--remote-debugging-address=0.0.0.0", \
  "--remote-debugging-port=9222", \
  "--no-sandbox", \
  "--disable-dev-shm-usage"]

# Run it
docker run -d -p 9222:9222 --name chrome-headless chromedp/headless-shell

# Connect from host
curl -s http://localhost:9222/json/version

For Docker, chromedp/headless-shell is the minimal image (~100MB). If you need the full browser with font rendering and locales, use browserless/chrome or build your own from the Debian Chromium package.

Android device debugging

Chrome on Android supports USB debugging via ADB:

# Enable USB Debugging in Android Developer Settings first

# Forward the device's debugging port to your machine
adb forward tcp:9222 localabstract:chrome_devtools_remote

# Now localhost:9222 reaches the phone's Chrome
curl -s http://localhost:9222/json/list

# Or use chrome://inspect with USB discovery enabled

This works with the standard Chrome app on Android. Enable "USB web debugging" in Chrome's developer settings (chrome://flags), or launch Chrome with --remote-debugging-port via ADB shell.

Backtraces & stack capture

CDP's Debugger domain gives you deep access to the JavaScript call stack, pause/resume control, and exception handling. This is where the protocol really shines for debugging complex applications.

Pause on exceptions

// Pause on all exceptions (caught and uncaught)
await cdp.send('Debugger.enable');
await cdp.send('Debugger.setPauseOnExceptions', {
  state: 'all'  // 'none' | 'uncaught' | 'all'
});

// Listen for when execution pauses
cdp.on('Debugger.paused', async (params) => {
  console.log('Paused. Reason:', params.reason);
  console.log('Hit breakpoints:', params.hitBreakpoints);

  // Walk the call frames
  for (const frame of params.callFrames) {
    console.log(`  ${frame.functionName || '(anonymous)'}`
      + ` at ${frame.url}:${frame.location.lineNumber}`);

    // Inspect scope variables at this frame
    for (const scope of frame.scopeChain) {
      if (scope.type === 'local') {
        const { result } = await cdp.send(
          'Runtime.getProperties', {
            objectId: scope.object.objectId,
            ownProperties: true
          }
        );
        console.log('    Local vars:',
          result.map(p => `${p.name}=${p.value?.description}`));
      }
    }
  }

  // Resume execution
  await cdp.send('Debugger.resume');
});

Set breakpoints by URL pattern

// Break on a specific line
await cdp.send('Debugger.setBreakpointByUrl', {
  lineNumber: 42,
  urlRegex: '.*app\\.js$'
});

// Conditional breakpoint
await cdp.send('Debugger.setBreakpointByUrl', {
  lineNumber: 100,
  url: 'https://example.com/app.js',
  condition: 'items.length > 50'
});

Async stack traces

// Enable async call stacks (critical for understanding
// promise chains, setTimeout callbacks, event handlers)
await cdp.send('Debugger.setAsyncCallStackDepth', {
  maxDepth: 32
});

// Now when paused, callFrames will include the async parent chain
// params.asyncStackTrace links to the parent async context
cdp.on('Debugger.paused', (params) => {
  let asyncTrace = params.asyncStackTrace;
  while (asyncTrace) {
    console.log(`Async: ${asyncTrace.description}`);
    for (const frame of asyncTrace.callFrames) {
      console.log(`  ${frame.functionName} (${frame.url}:${frame.lineNumber})`);
    }
    asyncTrace = asyncTrace.parent;
  }
});

Runtime stack traces (no pausing needed)

// Get a stack trace from any console message
await cdp.send('Runtime.enable');

cdp.on('Runtime.consoleAPICalled', (params) => {
  console.log(`console.${params.type}:`,
    params.args.map(a => a.value || a.description));
  if (params.stackTrace) {
    for (const frame of params.stackTrace.callFrames) {
      console.log(`  at ${frame.functionName} (${frame.url}:${frame.lineNumber})`);
    }
  }
});

// Capture stack traces for uncaught exceptions
cdp.on('Runtime.exceptionThrown', (params) => {
  const ex = params.exceptionDetails;
  console.log('Exception:', ex.text);
  if (ex.stackTrace) {
    ex.stackTrace.callFrames.forEach(f =>
      console.log(`  ${f.functionName} ${f.url}:${f.lineNumber}:${f.columnNumber}`)
    );
  }
});

Console.trace() capture

// Inject a console.trace() call to get a backtrace from
// anywhere in the app without setting breakpoints
await cdp.send('Runtime.evaluate', {
  expression: `
    const _origFetch = window.fetch;
    window.fetch = function(...args) {
      console.trace('fetch called with:', args[0]);
      return _origFetch.apply(this, args);
    };
  `
});
// Every fetch() call now emits a full stack trace via
// Runtime.consoleAPICalled with type 'trace'

Profiling & performance

CPU profiling

await cdp.send('Profiler.enable');
await cdp.send('Profiler.start');

// ... do the thing you want to profile ...

const { profile } = await cdp.send('Profiler.stop');

// profile.nodes = array of call tree nodes with hitCount + children
// profile.startTime / endTime in microseconds
// profile.samples = array of node IDs sampled at each interval
// profile.timeDeltas = microsecond deltas between samples

// Save as .cpuprofile format (Chrome DevTools can open this)
fs.writeFileSync('profile.cpuprofile', JSON.stringify(profile));

Heap snapshots

await cdp.send('HeapProfiler.enable');

// Collect chunks as they stream
let snapshotData = '';
cdp.on('HeapProfiler.addHeapSnapshotChunk', ({ chunk }) => {
  snapshotData += chunk;
});

await cdp.send('HeapProfiler.takeHeapSnapshot', {
  reportProgress: true,
  treatGlobalObjectsAsRoots: true,
  captureNumericValue: true
});

// Save as .heapsnapshot (loadable in DevTools Memory panel)
fs.writeFileSync('heap.heapsnapshot', snapshotData);

Performance timeline traces

// Record a full performance trace (same data as DevTools Performance panel)
await cdp.send('Tracing.start', {
  categories: '-*,devtools.timeline,v8.execute,disabled-by-default-devtools.timeline,disabled-by-default-devtools.timeline.frame,toplevel,blink.console,blink.user_timing,latencyInfo,disabled-by-default-devtools.timeline.stack,disabled-by-default-v8.cpu_profiler,disabled-by-default-v8.cpu_profiler.hires',
  options: 'sampling-frequency=10000'
});

// ... interact with the page ...

const chunks = [];
cdp.on('Tracing.dataCollected', ({ value }) => chunks.push(...value));

await cdp.send('Tracing.end');

// Wait for tracingComplete event
await new Promise(resolve =>
  cdp.on('Tracing.tracingComplete', resolve)
);

// Save as .json trace file (load in chrome://tracing or DevTools)
fs.writeFileSync('trace.json', JSON.stringify(chunks));

Performance metrics (instant readings)

await cdp.send('Performance.enable', {
  timeDomain: 'timeTicks'
});

const { metrics } = await cdp.send('Performance.getMetrics');

// Returns an array of { name, value } objects:
// - Timestamp, Documents, Frames, JSEventListeners
// - Nodes, LayoutCount, RecalcStyleCount, LayoutDuration
// - RecalcStyleDuration, ScriptDuration, TaskDuration
// - JSHeapUsedSize, JSHeapTotalSize, FirstMeaningfulPaint
// - DomContentLoaded, NavigationStart

for (const m of metrics) {
  console.log(`${m.name}: ${m.value}`);
}

DevTools hacks

Beyond the standard automation use cases, CDP opens up capabilities that are genuinely hard to get any other way.

Network interception and modification

// Intercept and modify requests in flight
await cdp.send('Fetch.enable', {
  patterns: [
    { urlPattern: '*', requestStage: 'Request' },
    { urlPattern: '*', requestStage: 'Response' }
  ]
});

cdp.on('Fetch.requestPaused', async (params) => {
  if (params.responseStatusCode) {
    // Response stage: modify the response body
    const { body, base64Encoded } = await cdp.send(
      'Fetch.getResponseBody',
      { requestId: params.requestId }
    );

    let decoded = base64Encoded
      ? Buffer.from(body, 'base64').toString()
      : body;

    // Inject a script into every HTML response
    if (params.responseHeaders
        .some(h => h.name.toLowerCase() === 'content-type'
          && h.value.includes('text/html'))) {
      decoded = decoded.replace(
        '</head>',
        '<script>console.log("injected")</script></head>'
      );
    }

    await cdp.send('Fetch.fulfillRequest', {
      requestId: params.requestId,
      responseCode: params.responseStatusCode,
      responseHeaders: params.responseHeaders,
      body: Buffer.from(decoded).toString('base64')
    });
  } else {
    // Request stage: add/modify headers
    const headers = [...params.request.headers];
    await cdp.send('Fetch.continueRequest', {
      requestId: params.requestId,
      headers: [
        ...Object.entries(params.request.headers)
          .map(([name, value]) => ({ name, value })),
        { name: 'X-Custom-Header', value: 'injected' }
      ]
    });
  }
});

Coverage analysis

// Find unused CSS and JS on a page
await cdp.send('Profiler.enable');
await cdp.send('Profiler.startPreciseCoverage', {
  callCount: true,
  detailed: true
});
await cdp.send('CSS.enable');
await cdp.send('CSS.startRuleUsageTracking');

await page.goto('https://example.com');
await page.waitForTimeout(3000);

// JS coverage
const { result: jsCoverage } = await cdp.send(
  'Profiler.takePreciseCoverage'
);

for (const script of jsCoverage) {
  const total = script.functions
    .reduce((sum, fn) => sum + fn.ranges
      .reduce((s, r) => s + r.endOffset - r.startOffset, 0), 0);
  const used = script.functions
    .reduce((sum, fn) => sum + fn.ranges
      .filter(r => r.count > 0)
      .reduce((s, r) => s + r.endOffset - r.startOffset, 0), 0);
  console.log(`${script.url}: ${((used/total)*100).toFixed(1)}% used`);
}

// CSS coverage
const { ruleUsage } = await cdp.send('CSS.stopRuleUsageTracking');
const unusedRules = ruleUsage.filter(r => !r.used);
console.log(`${unusedRules.length} unused CSS rules`);

DOM snapshotting for diffing

// Capture a complete DOM snapshot (useful for visual regression)
const snapshot = await cdp.send('DOMSnapshot.captureSnapshot', {
  computedStyles: ['background-color', 'color', 'font-size',
    'display', 'visibility', 'opacity']
});

// Returns documents[] with nodes, layout, text, styles
// Great for building custom accessibility auditors or
// structural page comparison tools

Geolocation, device, and sensor emulation

// Fake GPS location
await cdp.send('Emulation.setGeolocationOverride', {
  latitude: 37.7749,
  longitude: -122.4194,
  accuracy: 100
});

// Emulate a device
await cdp.send('Emulation.setDeviceMetricsOverride', {
  width: 375,
  height: 812,
  deviceScaleFactor: 3,
  mobile: true
});

// Emulate network conditions
await cdp.send('Network.emulateNetworkConditions', {
  offline: false,
  latency: 150,          // ms
  downloadThroughput: 1.6 * 1024 * 1024 / 8,  // 1.6 Mbps
  uploadThroughput: 750 * 1024 / 8             // 750 Kbps
});

// Override timezone
await cdp.send('Emulation.setTimezoneOverride', {
  timezoneId: 'Asia/Tokyo'
});

// Override locale
await cdp.send('Emulation.setLocaleOverride', {
  locale: 'ja-JP'
});

// Simulate vision deficiency
await cdp.send('Emulation.setEmulatedVisionDeficiency', {
  type: 'deuteranopia'  // protanopia, tritanopia, achromatopsia, blurredVision
});

Synthetic input events

// Synthesize mouse clicks, keyboard input, touch events
// These go through the browser's actual input pipeline

// Click at coordinates
await cdp.send('Input.dispatchMouseEvent', {
  type: 'mousePressed', x: 100, y: 200,
  button: 'left', clickCount: 1
});
await cdp.send('Input.dispatchMouseEvent', {
  type: 'mouseReleased', x: 100, y: 200,
  button: 'left', clickCount: 1
});

// Type text (uses Input.dispatchKeyEvent under the hood)
for (const char of 'hello world') {
  await cdp.send('Input.dispatchKeyEvent', {
    type: 'keyDown', text: char
  });
  await cdp.send('Input.dispatchKeyEvent', {
    type: 'keyUp'
  });
}

// Touch events for mobile emulation
await cdp.send('Input.dispatchTouchEvent', {
  type: 'touchStart',
  touchPoints: [{ x: 150, y: 300 }]
});
await cdp.send('Input.dispatchTouchEvent', {
  type: 'touchEnd',
  touchPoints: []
});

Cookie and storage manipulation

// Read all cookies
const { cookies } = await cdp.send('Network.getAllCookies');

// Set a cookie
await cdp.send('Network.setCookie', {
  name: 'session',
  value: 'abc123',
  domain: 'example.com',
  path: '/',
  httpOnly: true,
  secure: true
});

// Clear all cookies
await cdp.send('Network.clearBrowserCookies');

// Clear localStorage/sessionStorage/indexedDB/caches
await cdp.send('Storage.clearDataForOrigin', {
  origin: 'https://example.com',
  storageTypes: 'all'
});

PDF generation

const { data } = await cdp.send('Page.printToPDF', {
  landscape: false,
  displayHeaderFooter: true,
  headerTemplate: '<div style="font-size:8px;text-align:center;width:100%">Confidential</div>',
  footerTemplate: '<div style="font-size:8px;text-align:center;width:100%">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
  printBackground: true,
  preferCSSPageSize: true
});

fs.writeFileSync('page.pdf', Buffer.from(data, 'base64'));

Accessibility tree inspection

// Get the full accessibility tree
const { nodes } = await cdp.send('Accessibility.getFullAXTree');

// Each node has: role, name, value, description, children
// Build custom a11y auditors that run in CI
for (const node of nodes) {
  if (node.role?.value === 'img' && !node.name?.value) {
    console.log('Image missing alt text:', node.backendDOMNodeId);
  }
}

Intercept file downloads

// Control where downloads go (headless mode)
await cdp.send('Browser.setDownloadBehavior', {
  behavior: 'allowAndName',
  downloadPath: '/tmp/downloads',
  eventsEnabled: true
});

cdp.on('Browser.downloadProgress', (params) => {
  console.log(`Download ${params.guid}: ${params.state}`);
  if (params.state === 'completed') {
    console.log('Saved to:', params.guid);
  }
});

Screencast (stream the viewport)

// Stream frames as base64 images
await cdp.send('Page.startScreencast', {
  format: 'jpeg',
  quality: 60,
  maxWidth: 1280,
  maxHeight: 720,
  everyNthFrame: 2
});

cdp.on('Page.screencastFrame', async (params) => {
  // params.data = base64 jpeg
  // params.metadata = { offsetTop, pageScaleFactor, ... }
  // params.sessionId = acknowledge to receive next frame

  // Process the frame (save, stream to websocket, etc.)
  processFrame(params.data);

  // Acknowledge to get the next frame
  await cdp.send('Page.screencastFrameAck', {
    sessionId: params.sessionId
  });
});

Script injection and monkey-patching

// Run a script on every new document (before any page JS executes)
await cdp.send('Page.addScriptToEvaluateOnNewDocument', {
  source: `
    // Override navigator properties (stealth)
    Object.defineProperty(navigator, 'webdriver', { get: () => false });

    // Instrument all XHR calls
    const _open = XMLHttpRequest.prototype.open;
    XMLHttpRequest.prototype.open = function(method, url) {
      console.log('[XHR]', method, url);
      return _open.apply(this, arguments);
    };

    // Hook into postMessage
    const _postMessage = window.postMessage;
    window.postMessage = function(msg, origin) {
      console.log('[postMessage]', msg, origin);
      return _postMessage.apply(this, arguments);
    };

    // Performance observer for long tasks
    new PerformanceObserver((list) => {
      for (const entry of list.getEntries()) {
        if (entry.duration > 50) {
          console.warn('[LongTask]', entry.duration.toFixed(1) + 'ms', entry.name);
        }
      }
    }).observe({ type: 'longtask', buffered: true });
  `
});

CDP command reference

The full protocol has 40+ domains and hundreds of commands. This reference covers the ones you'll actually use. Each entry shows the method signature, key parameters, and what it's useful for.

Convention: Domain.method for commands, Domain.eventName for events.

Page domain

Controls page navigation, lifecycle, screenshots, and printing.

Runtime domain

Execute JavaScript, inspect objects, and subscribe to console output.

Network domain

Monitor and modify HTTP traffic.

DOM domain

Query and manipulate the DOM tree.

Debugger domain

Breakpoints, stepping, call stacks, and source maps.

Profiler domain

CPU profiling and code coverage.

Performance domain

Target domain

Manage browser targets: tabs, workers, service workers, extensions.

Input domain

Synthesize keyboard, mouse, and touch events.

Emulation domain

Override device characteristics, location, timezone, vision, media, and more.

Security domain

Log domain

Fetch domain

Request interception with more control than Network.setRequestInterception.

Other domains worth knowing

Further reading

• Chrome DevTools Protocol Viewer (official, auto-generated from Chromium source)
• Puppeteer documentation
• Playwright documentation
• Awesome Chrome DevTools (curated tools and libraries)
• chrome://flags for experimental features, chrome://inspect for device discovery, chrome://tracing for loading trace files