chrome-remote-interface

What is chrome-remote-interface?

The chrome-remote-interface npm package is a tool that allows you to interact with the Chrome DevTools Protocol. This enables you to control, inspect, and debug web pages and web applications programmatically.

What are chrome-remote-interface's main functionalities?

Remote Debugging

This feature allows you to remotely debug a web page. The code sample demonstrates how to navigate to a URL, wait for the page to load, capture a screenshot, and save it to a file.

const CDP = require('chrome-remote-interface');

CDP(async (client) => {
    const {Network, Page} = client;

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

    Page.navigate({url: 'https://example.com'});
    Page.loadEventFired(async () => {
        const result = await Page.captureScreenshot();
        require('fs').writeFileSync('screenshot.png', result.data, 'base64');
        client.close();
    });
}).on('error', (err) => {
    console.error(err);
});

Network Monitoring

This feature allows you to monitor network requests and responses. The code sample demonstrates how to log URLs of requests and responses.

const CDP = require('chrome-remote-interface');

CDP(async (client) => {
    const {Network} = client;

    await Network.enable();

    Network.requestWillBeSent((params) => {
        console.log('Request:', params.request.url);
    });

    Network.responseReceived((params) => {
        console.log('Response:', params.response.url);
    });
}).on('error', (err) => {
    console.error(err);
});

JavaScript Execution

This feature allows you to execute JavaScript in the context of the web page. The code sample demonstrates how to evaluate a JavaScript expression to get the document title.

const CDP = require('chrome-remote-interface');

CDP(async (client) => {
    const {Runtime} = client;

    await Runtime.enable();

    const result = await Runtime.evaluate({expression: 'document.title'});
    console.log('Title:', result.result.value);

    client.close();
}).on('error', (err) => {
    console.error(err);
});

Other packages similar to chrome-remote-interface

puppeteer

Puppeteer is a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol. It is more user-friendly and higher-level compared to chrome-remote-interface, making it easier to perform common tasks like taking screenshots, generating PDFs, and automating form submissions.

selenium-webdriver

Selenium WebDriver is a popular tool for automating web applications for testing purposes. It provides a more comprehensive solution for browser automation, supporting multiple browsers and programming languages. Compared to chrome-remote-interface, it is more focused on testing and less on low-level browser control.

playwright

Playwright is a Node library to automate Chromium, Firefox, and WebKit with a single API. It is similar to Puppeteer but supports multiple browsers. It offers more advanced features like capturing videos of test runs and intercepting network requests, making it a more versatile tool compared to chrome-remote-interface.

README

chrome-remote-interface

Remote Debugging Protocol interface that helps to instrument Chrome by providing a simple abstraction of the two main objects exposed by the protocol in a Node.js fashion: commands and notifications.

chrome-remote-interface is listed among third-party Chrome debugging protocol clients.

This module should work with every application implementing the Chrome Remote Debugging Protocol. In particular, it has been tested against the following implementations:

Implementation	Notes
Google Chrome	native support; enable port forwarding in Chrome for Android
Microsoft Edge	via the Edge Diagnostics Adapter
Node.js	via --inspect (with --port 9229) or via node-inspector (by connecting to ws://127.0.0.1:8080/?port=5858 by default)

Installation

npm install chrome-remote-interface

Chrome setup

Chrome needs to be started with the --remote-debugging-port=<port> option to enable the Remote Debugging Protocol, for example:

google-chrome --remote-debugging-port=9222

Sample API usage

The following snippet loads https://github.com and dumps every request made:

const Chrome = require('chrome-remote-interface');
Chrome(function (chrome) {
    with (chrome) {
        Network.requestWillBeSent(function (params) {
            console.log(params.request.url);
        });
        Page.loadEventFired(close);
        Network.enable();
        Page.enable();
        once('ready', function () {
            Page.navigate({'url': 'https://github.com'});
        });
    }
}).on('error', function (err) {
    console.error('Cannot connect to Chrome:', err);
});

Bundled client

This module comes with a bundled client application that can be used to interactively control Chrome.

Tab management

The bundled client exposes subcommands to interact with the HTTP frontend (e.g., List, New, etc.), run with --help to display the list of available options.

Here are some examples:

$ chrome-remote-interface new 'http://example.com'
{ description: '',
  devtoolsFrontendUrl: '/devtools/inspector.html?ws=localhost:9222/devtools/page/b049bb56-de7d-424c-a331-6ae44cf7ae01',
  id: 'b049bb56-de7d-424c-a331-6ae44cf7ae01',
  thumbnailUrl: '/thumb/b049bb56-de7d-424c-a331-6ae44cf7ae01',
  title: '',
  type: 'page',
  url: 'http://example.com/',
  webSocketDebuggerUrl: 'ws://localhost:9222/devtools/page/b049bb56-de7d-424c-a331-6ae44cf7ae01' }
$ chrome-remote-interface close 'b049bb56-de7d-424c-a331-6ae44cf7ae01'

Inspection

Using the inspect subcommand it is possible to perform command execution and event binding in a REPL fashion. But unlike the regular API the callbacks are overridden to conveniently display the result of the commands and the message of the events. Also, the event binding is simplified here, executing a shorthand method (e.g., Page.loadEventFired()) toggles the event registration.

Here is a sample session:

$ chrome-remote-interface inspect
>>> Runtime.evaluate({expression: 'window.location.toString()'})
{ result:
   { result:
      { type: 'string',
        value: 'https://www.google.it/_/chrome/newtab?espv=2&ie=UTF-8' },
     wasThrown: false } }
>>> Page.enable()
{ result: {} }
>>> Page.loadEventFired() // registered
{ 'Page.loadEventFired': true }
>>> Page.loadEventFired() // unregistered
{ 'Page.loadEventFired': false }
>>> Page.loadEventFired() // registered
{ 'Page.loadEventFired': true }
>>> Page.navigate({url: 'https://github.com'})
{ result: { frameId: '28677.1' } }
{ 'Page.loadEventFired': { timestamp: 21385.383076 } }
>>> Runtime.evaluate({expression: 'window.location.toString()'})
{ result:
   { result: { type: 'string', value: 'https://github.com/' },
     wasThrown: false } }

Event filtering

To reduce the amount of data displayed by the event listeners it is possible to provide a filter function. In this example only the resource URL is shown:

$ chrome-remote-interface inspect
>>> Network.enable()
{ result: {} }
>>> Network.requestWillBeSent(params => params.request.url)
{ 'Network.requestWillBeSent': 'params => params.request.url' }
>>> Page.navigate({url: 'https://www.wikipedia.org'})
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/' }
{ result: { frameId: '5530.1' } }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia_wordmark.png' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia-logo-v2.png' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/js/index-3b68787aa6.js' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/js/gt-ie9-c84bf66d33.js' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/img/sprite-bookshelf_icons.png?16ed124e8ca7c5ce9d463e8f99b2064427366360' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/img/sprite-project-logos.png?9afc01c5efe0a8fb6512c776955e2ad3eb48fbca' }

Embedded documentation

In both the REPL and the regular API every object of the protocol is decorated with the information available through the Remote Debugging Protocol. The category field determines if the member is a command, an event or a type.

Remember that the REPL interface provides completion. For example to learn how to call Page.navigate:

>>> Page.navigate
{ [Function]
  category: 'command',
  parameters: { url: { type: 'string', description: 'URL to navigate the page to.' } },
  returns:
   [ { name: 'frameId',
       '$ref': 'FrameId',
       hidden: true,
       description: 'Frame id that will be navigated.' } ],
  description: 'Navigates current page to the given URL.',
  handlers: [ 'browser', 'renderer' ] }

To learn about the parameters returned by the Network.requestWillBeSent event:

>>> Network.requestWillBeSent
{ [Function]
  category: 'event',
  description: 'Fired when page is about to send HTTP request.',
  parameters:
   { requestId: { '$ref': 'RequestId', description: 'Request identifier.' },
     frameId:
      { '$ref': 'Page.FrameId',
        description: 'Frame identifier.',
        hidden: true },
     loaderId: { '$ref': 'LoaderId', description: 'Loader identifier.' },
     documentURL:
      { type: 'string',
        description: 'URL of the document this request is loaded for.' },
     request: { '$ref': 'Request', description: 'Request data.' },
     timestamp: { '$ref': 'Timestamp', description: 'Timestamp.' },
     wallTime:
      { '$ref': 'Timestamp',
        hidden: true,
        description: 'UTC Timestamp.' },
     initiator: { '$ref': 'Initiator', description: 'Request initiator.' },
     redirectResponse:
      { optional: true,
        '$ref': 'Response',
        description: 'Redirect response data.' },
     type:
      { '$ref': 'Page.ResourceType',
        optional: true,
        hidden: true,
        description: 'Type of this resource.' } } }

To inspect the Network.Request (note that unlike commands and events, types are named in upper camel case) type:

>>> Network.Request
{ category: 'type',
  id: 'Request',
  type: 'object',
  description: 'HTTP request data.',
  properties:
   { url: { type: 'string', description: 'Request URL.' },
     method: { type: 'string', description: 'HTTP request method.' },
     headers: { '$ref': 'Headers', description: 'HTTP request headers.' },
     postData:
      { type: 'string',
        optional: true,
        description: 'HTTP POST request data.' },
     mixedContentType:
      { optional: true,
        type: 'string',
        enum: [Object],
        description: 'The mixed content status of the request, as defined in http://www.w3.org/TR/mixed-content/' },
     initialPriority:
      { '$ref': 'ResourcePriority',
        description: 'Priority of the resource request at the time request is sent.' } } }

Remote Debugging Protocol versions

Currently it is not possible to fetch the protocol descriptor (protocol.json) directly from the instrumented Chrome instance (see #10). Rather, that file can be fetched from the proper source repository at every connection. By default, the local version is used. That file is manually updated from time to time using scripts/update-protocol.sh and pushed to this repository.

To override the above behavior there are basically three options:

1. pass a custom protocol descriptor upon connection;

2. use the raw version of the commands and events interface;

3. update the local copy with scripts/update-protocol.sh (not present when fetched with npm install).

API

module([options], [callback])

Connects to a remote instance of Chrome using the Remote Debugging Protocol.

options is an object with the following optional properties:

• host: HTTP frontend host. Defaults to localhost;

• port: HTTP frontend port. Defaults to 9222;

• chooseTab: determines which tab this instance should attach to. The behavior changes according to the type:

  • a function that takes the array returned by the List method and returns the numeric index of a tab;
  • a tab object like those returned by the New and List methods;
  • a string representing the raw WebSocket URL, in this case host and port are not used to fetch the tab list.

  Defaults to a function which returns the currently active tab (function (tabs) { return 0; });

• protocol: Remote Debugging Protocol descriptor object. Defaults to use the protocol chosen according to the remote option;

• remote: a boolean indicating whether the protocol must be fetched remotely or if the local version must be used. It has no effect if the protocol option is set. Defaults to false.

callback is a listener automatically added to the connect event of the returned EventEmitter. When callback is omitted a Promise object is returned which becomes fulfilled if the connect event is triggered and rejected if any of the disconnect or error events are triggered.

The EventEmitter supports the following events:

Event: 'connect'

function (chrome) {}

Emitted when the connection to Chrome is established.

chrome is an instance of the Chrome class.

Event: 'disconnect'

function () {}

Emitted when Chrome closes the connection, e.g., if the user opens the DevTools for the currently inspected tab.

Event: 'error'

function (err) {}

Emitted if http://host:port/json can't be reached or if it's not possible to connect to Chrome's remote debugging WebSocket.

err is an instance of Error.

module.Protocol([options], [callback])

Fetch the Remote Debugging Protocol descriptor.

options is an object with the following optional properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• remote: a boolean indicating whether the protocol must be fetched remotely or if the local version must be returned. If it is not possible to fulfill the request then the local version is used. Defaults to false.

callback is executed when the protocol is fetched, it gets the following arguments:

• err: a Error object indicating the success status;
• protocol: an object with the following properties:
  • remote: a boolean indicating whether the returned descriptor is the remote version or not (due to user choice or error);
  • descriptor: the Remote Debugging Protocol descriptor.

When callback is omitted a Promise object is returned.

For example:

const Chrome = require('chrome-remote-interface');
Chrome.Protocol(function (err, protocol) {
    if (!err) {
        console.log(JSON.stringify(protocol.descriptor, null, 4));
    }
});

module.List([options], [callback])

Request the list of the available open tabs of the remote Chrome instance.

options is an object with the following optional properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222.

callback is executed when the list is correctly received, it gets the following arguments:

• err: a Error object indicating the success status;
• tabs: the array returned by http://host:port/json/list containing the tab list.

When callback is omitted a Promise object is returned.

For example:

const Chrome = require('chrome-remote-interface');
Chrome.List(function (err, tabs) {
    if (!err) {
        console.log(tabs);
    }
});

module.New([options], [callback])

Create a new tab in the remote Chrome instance.

options is an object with the following optional properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• url: URL to load in the new tab. Defaults to about:blank.

callback is executed when the tab is created, it gets the following arguments:

• err: a Error object indicating the success status;
• tab: the object returned by http://host:port/json/new containing the tab.

When callback is omitted a Promise object is returned.

For example:

const Chrome = require('chrome-remote-interface');
Chrome.New(function (err, tab) {
    if (!err) {
        console.log(tab);
    }
});

module.Activate([options], [callback])

Activate an open tab of the remote Chrome instance.

options is an object with the following properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• id: Tab id. Required, no default.

callback is executed when the response to the activation request is received. It gets the following arguments:

• err: a Error object indicating the success status;

When callback is omitted a Promise object is returned.

For example:

const Chrome = require('chrome-remote-interface');
Chrome.Activate({'id': 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, function (err) {
    if (!err) {
        console.log('success! tab is closing');
    }
});

module.Close([options], [callback])

Close an open tab of the remote Chrome instance.

options is an object with the following properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• id: Tab id. Required, no default.

callback is executed when the response to the close request is received. It gets the following arguments:

• err: a Error object indicating the success status;

When callback is omitted a Promise object is returned.

For example:

const Chrome = require('chrome-remote-interface');
Chrome.Close({'id': 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, function (err) {
    if (!err) {
        console.log('success! tab is closing');
    }
});

Note that the callback is fired when the tab is queued for removal, but the actual removal will occur asynchronously.

module.Version([options], [callback])

Request version information from the remote Chrome instance.

options is an object with the following optional properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222.

callback is executed when the version information is correctly received, it gets the following arguments:

• err: a Error object indicating the success status;
• info: a JSON object returned by http://host:port/json/version containing the version information.

When callback is omitted a Promise object is returned.

For example:

const Chrome = require('chrome-remote-interface');
Chrome.Version(function (err, info) {
    if (!err) {
        console.log(info);
    }
});

Class: Chrome

Event: 'event'

function (message) {}

Emitted when Chrome sends a notification through the WebSocket.

message is the object received, it has the following properties:

• method: a string describing the notification (e.g., 'Network.requestWillBeSent');
• params: an object containing the payload.

Refer to the Remote Debugging Protocol specifications for more information.

For example:

chrome.on('event', function (message) {
    if (message.method === 'Network.requestWillBeSent') {
        console.log(message.params);
    }
});

Event: '<method>'

function (params) {}

Emitted when Chrome sends a notification for <method> through the WebSocket.

params is an object containing the payload.

This is just a utility event which allows to easily listen for specific notifications (see the above event), for example:

chrome.on('Network.requestWillBeSent', console.log);

Event: 'ready'

function () {}

Emitted every time that there are no more pending commands waiting for a response from Chrome. Note that the interaction with Chrome is asynchronous so the only way to serialize a sequence of commands is to use the callback provided by the chrome.send method. This event acts as a barrier and it is useful to avoid the callback hell in certain simple situations.

For example to load a URL only after having enabled the notifications of both Network and Page domains:

chrome.Network.enable();
chrome.Page.enable();
chrome.once('ready', function () {
    chrome.Page.navigate({'url': 'https://github.com'});
});

In this particular case, not enforcing this kind of serialization may cause that Chrome doesn't properly deliver the desired notifications the client.

chrome.send(method, [params], [callback])

Issue a command to Chrome.

method is a string describing the command.

params is an object containing the payload.

callback is executed when Chrome sends a response to this command, it gets the following arguments:

• error: a boolean value indicating the success status, as reported by Chrome;
• response: an object containing either the response sent from Chrome (result field, if error === false) or the indication of the error (error field, if error === true).

When callback is omitted a Promise object is returned instead, with the fulfilled/rejected states implemented according to the error parameter.

Note that the field id mentioned in the Remote Debugging Protocol specifications is managed internally and it's not exposed to the user.

For example:

chrome.send('Page.navigate', {'url': 'https://github.com'}, console.log);

chrome.<domain>.<method>([params], [callback])

Just a shorthand for:

chrome.send('<domain>.<method>', params, callback);

For example:

chrome.Page.navigate({'url': 'https://github.com'}, console.log);

chrome.<domain>.<event>(callback)

Just a shorthand for:

chrome.on('<domain>.<event>', callback);

For example:

chrome.Network.requestWillBeSent(console.log);

chrome.close([callback])

Close the connection to Chrome.

callback is executed when the WebSocket is successfully closed.

When callback is omitted a Promise object is returned.

Contributors

• Andrey Sidorov
• Greg Cochard

Resources

• Chrome Debugging Protocol
• Chrome Debugging Protocol Viewer
• Chrome Debugging Protocol Google group
• Showcase Chrome Debugging Protocol Clients