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.

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.

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

REPL interface and embedded documentation

This module comes with a REPL interface that can be used to interactively control Chrome. The context is set to the chrome object so any issued command operates on it, just like the statements contained in the with block in the above example. Here's a sample session:

chrome> Network.enable()
chrome> Network.requestWillBeSent(console.log)
chrome> Page.navigate({url: 'https://github.com'})

Using the provided help field it's possible to obtain information on the events and methods available through the Remote Debugging Protocol. For example to learn how to call Page.navigate type:

chrome> Page.navigate.help
{ name: 'navigate',
  parameters:
   [ { name: 'url',
       type: 'string',
       description: 'URL to navigate the page to.' } ],
  description: 'Navigates current page to the given URL.' }

For what concerns the types instead, just type its name:

chrome> Network.Timestamp
{ id: 'Timestamp',
  type: 'number',
  description: 'Number of seconds since epoch.' }

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: Remote Debugging Protocol host. Defaults to localhost;
• port: Remote Debugging Protocol port. Defaults to 9222;
• chooseTab: callback used to determine which remote tab attach to. Takes the array returned by http://host:port/json containing the tab list and must return the numeric index of a tab. Defaults to a function that returns the active one (function (tabs) { return 0; }).

callback is a listener automatically added to the connect event of the returned EventEmitter.

Returns an EventEmitter that 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: '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.listTabs([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: Remote Debugging Protocol host. Defaults to localhost;
• port: Remote Debugging Protocol 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 containing the tab list.

For example:

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

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 message.
• params: an object containing the payload.

Refer to the Remote Debugging Protocol specifications for more information.

Event: method

function (params) {}

Emitted when Chrome sends a notification classified as method through the WebSocket.

params is an object containing the payload.

This is just a utility event that allows to easily filter out specific notifications (see the documentation of event), for example:

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

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

Issue a command to Chrome.

method is a string describing the message.

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;
• response: an object containing either the response sent from Chrome or the indication of the error.

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

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

Just a shorthand for:

chrome.send('Domain.method', params, callback);

For example:

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

chrome.Domain.event(callback)

Just a shorthand for:

chrome.on('Domain.event', callback);

For example:

chrome.Network.requestWillBeSent(console.log);

chrome.close()

Close the connection to Chrome.

Contributors

• Andrey Sidorov

Resources

• Chrome Developer Tools: Remote Debugging Protocol v1.0