Chrome DevTool protocol (CDP)

Enabling the DevTools protocol

To enable the DevTools protocol, you need to start chrome with the –remote-debugging-port flag

• In Headless mode (without the UI)

google-chrome-stable --headless --remote-debugging-port=9222 &

# With the UI
google-chrome --remote-debugging-port=9222

DevTools listening on ws://127.0.0.1:36775/devtools/browser/a292f96c-7332-4ce8-82a9-7411f3bd280a

Test that it's up

Since you don't have browser UI to see the page, you can navigate to http://localhost:9222 in another browser to check that everything is working.

You should see a list of inspectable pages where you can click through and see what Headless is rendering.

Client Connection and request

• The client create a WebSocket to connect to the URL
• The client start sending CDP commands (based on JSONRPC)

Directly via Websocket

Create a websocket and issue CDP commands. ²⁾

const ws = new WebSocket(browser.wsEndpoint(), {perMessageDeflate: false});
await new Promise(resolve => ws.once('open', resolve));
console.log('connected!');

ws.on('message', msg => console.log(msg));

console.log('Sending Target.setDiscoverTargets');
ws.send(JSON.stringify({
    id: 1,
    method: 'Target.setDiscoverTargets',
    params: {
      discover: true
    },
}));

With a CDP driver library

With the chrome-remote-interface CDP driver ³⁾

• Launch chrome with CDP enabled if needed

const execFile = require('child_process').execFile;
function launchHeadlessChrome(url, callback) {
  // Assuming MacOSx.
  const CHROME = '/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome';
  execFile(CHROME, ['--headless', '--disable-gpu', '--remote-debugging-port=9222', url], callback);
}

launchHeadlessChrome('https://www.chromestatus.com', (err, stdout, stderr) => {
  ...
});

• Use the chrome-remote-interface library

const CDP = require('chrome-remote-interface');
CDP((client) => {
  // Extract used DevTools domains.
  const {Page, Runtime} = client;

  // Enable events on domains we are interested in.
  Promise.all([
    Page.enable()
  ]).then(() => {
    return Page.navigate({url: 'https://example.com'});
  });

  // Evaluate outerHTML after page has loaded.
  Page.loadEventFired(() => {
    Runtime.evaluate({expression: 'document.body.outerHTML'}).then((result) => {
      console.log(result.result.value);
      client.close();
    });
  });
}).on('error', (err) => {
  console.error('Cannot connect to browser:', err);
});

Cli / Repl

The chrome-remote-interface has a client ⁴⁾ that permits to run as a client.

yarn global add chrome-remote-interface
# or
npm install -g chrome-remote-interface

It is possible to perform command execution (repl) and event binding, using the chrome-remote-interface inspect inspect subcommand

Protocol Monitor

To see all CDP command that performs the chrome browser, you can use the protocol-monitor. It provides a way to view all the CDP requests and responses made by DevTools.

Protocol Driver Library

Library are language wrapper around the chrome devtool protocol

Node:

• chrome-remote-interface

Php:

• chrome-devtools-protocol

C++ library:

• C Library

More:

• protocol-driver-libraries …

Higher Library

Higher level library based on the Protocol Driver Library

• WebDriver
• Puppeteer: Node library developed by the Chrome team - use a bundled version of Chromium instead of the one installed on your system.