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

async function example() {
    let client;
    try {
        / connect to endpoint
        client = await CDP();
        / extract domains
        const {Network, Page} = client;
        / setup handlers
        Network.requestWillBeSent(params) => {
            console.log(params.request.url);
        });
        / enable events then start!
        await Network.enable();
        await Page.enable();
        await Page.navigate({url: 'https://github.com'});
        await Page.loadEventFired();
    } catch (err) {
        console.error(err);
    } finally {
        if (client) {
            await client.close();
        }
    }
}

example();

npm install chrome-remote-interface

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

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

adb -d forward tcp:9222 localabstract:chrome_devtools_remote

adb shell grep -a webview_devtools_remote /proc/net/unix

adb forward tcp:9222 localabstract:webview_devtools_remote_<pid>

opera --remote-debugging-port=9222

node --inspect=9222 script.js

MicrosoftEdge.exe --devtools-server-port 9222 about:blank

firefox --remote-debugging-port 9222

$ 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'

$ chrome-remote-interface inspect
>>> Runtime.evaluate({expression: 'window.location.toString()'})
{ result: { type: 'string', value: 'about:blank' }
>>> Page.enable()
{}
>>> Page.loadEventFired(console.log)
[Function]
>>> Page.navigate({url: 'https://github.com'})
{ frameId: 'E1657E22F06E6E0BE13DFA8130C20298',
  loaderId: '439236ADE39978F98C20E8939A32D3A5' }
>>> { timestamp: 7454.721299 } / from Page.loadEventFired
>>> Runtime.evaluate({expression: 'window.location.toString()'})
{ result: { type: 'string', value: 'https://github.com/' }

>>> .help
[...]
.reset    Remove all the registered event handlers
.target   Display the current target

>>> 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' ] }

>>> 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.' }

>>> 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.' }

function criRequest(options, callback) {}

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

npm install --save-dev @types/chrome-remote-interface

The API consists of three parts:

• DevTools methods (for those implementations that support them, e.g., List, New, etc.);

• connection establishment;

• the actual protocol interaction.

Connects to a remote instance using the Chrome 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;

• secure: HTTPS/WSS frontend. Defaults to false;

• useHostName: do not perform a DNS lookup of the host. Defaults to false;

• alterPath: a function taking and returning the path fragment of a URL before that a request happens. Defaults to the identity function;

• target: determines which target this client should attach to. The behavior changes according to the type:

  • a function that takes the array returned by the List method and returns a target or its numeric index relative to the array;
  • a target 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 target list, yet they are used to complete the URL if relative;
  • a string representing the target id.

  Defaults to a function which returns the first available target according to the implementation (note that at most one connection can be established to the same target);

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

• local: 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.

These options are also valid properties of all the instances of the CDP class. In addition to that, the webSocketUrl field contains the currently used WebSocket URL.

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 the error event is triggered.

The EventEmitter supports the following events:

function (client) {}

Emitted when the connection to the WebSocket is established.

client is an instance of the CDP class.

function (err) {}

Emitted when http://host:port/json cannot be reached or if it is not possible to connect to the WebSocket.

err is an instance of Error.

Fetch the Chrome 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;
• secure: HTTPS/WSS frontend. Defaults to false;
• useHostName: do not perform a DNS lookup of the host. Defaults to false;
• alterPath: a function taking and returning the path fragment of a URL before that a request happens. Defaults to the identity function;
• local: a boolean indicating whether the protocol must be fetched remotely or if the local version must be returned. 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: the Chrome Debugging Protocol descriptor.

When callback is omitted a Promise object is returned.

For example:

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

Request the list of the available open targets/tabs of the remote instance.

options is an object with the following optional properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• secure: HTTPS/WSS frontend. Defaults to false;
• useHostName: do not perform a DNS lookup of the host. Defaults to false;
• alterPath: a function taking and returning the path fragment of a URL before that a request happens. Defaults to the identity function.

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

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

When callback is omitted a Promise object is returned.

For example:

const CDP = require('chrome-remote-interface');
CDP.List(err, targets) => {
    if (!err) {
        console.log(targets);
    }
});

Create a new target/tab in the remote instance.

options is an object with the following optional properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• secure: HTTPS/WSS frontend. Defaults to false;
• useHostName: do not perform a DNS lookup of the host. Defaults to false;
• alterPath: a function taking and returning the path fragment of a URL before that a request happens. Defaults to the identity function;
• url: URL to load in the new target/tab. Defaults to about:blank.

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

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

When callback is omitted a Promise object is returned.

For example:

const CDP = require('chrome-remote-interface');
CDP.New(err, target) => {
    if (!err) {
        console.log(target);
    }
});

Activate an open target/tab of the remote instance.

options is an object with the following properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• secure: HTTPS/WSS frontend. Defaults to false;
• useHostName: do not perform a DNS lookup of the host. Defaults to false;
• alterPath: a function taking and returning the path fragment of a URL before that a request happens. Defaults to the identity function;
• id: Target 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 CDP = require('chrome-remote-interface');
CDP.Activate({id: 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, (err) => {
    if (!err) {
        console.log('target is activated');
    }
});

Close an open target/tab of the remote instance.

options is an object with the following properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• secure: HTTPS/WSS frontend. Defaults to false;
• useHostName: do not perform a DNS lookup of the host. Defaults to false;
• alterPath: a function taking and returning the path fragment of a URL before that a request happens. Defaults to the identity function;
• id: Target 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 CDP = require('chrome-remote-interface');
CDP.Close({id: 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, (err) => {
    if (!err) {
        console.log('target is closing');
    }
});

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

Request version information from the remote instance.

options is an object with the following optional properties:

• host: HTTP frontend host. Defaults to localhost;
• port: HTTP frontend port. Defaults to 9222;
• secure: HTTPS/WSS frontend. Defaults to false;
• useHostName: do not perform a DNS lookup of the host. Defaults to false;
• alterPath: a function taking and returning the path fragment of a URL before that a request happens. Defaults to the identity function.

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 CDP = require('chrome-remote-interface');
CDP.Version(err, info) => {
    if (!err) {
        console.log(info);
    }
});

function (message) {}

Emitted when the remote instance sends any 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;
• sessionId: an optional string representing the session identifier.

Refer to the Chrome Debugging Protocol specification for more information.

For example:

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

function (params, sessionId) {}

Emitted when the remote instance sends a notification for <domain>.<method> through the WebSocket.

params is an object containing the payload.

sessionId is an optional string representing the session identifier.

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

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

Additionally, the equivalent <domain>.on('<method>', ...) syntax is available, for example:

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

function (params, sessionId) {}

Equivalent to the following but only for those events belonging to the given session:

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

function () {}

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

Users are encouraged to extensively check the response of each method and should prefer the promises API when dealing with complex asynchronous program flows.

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

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

In this particular case, not enforcing this kind of serialization may cause that the remote instance does not properly deliver the desired notifications the client.

function () {}

Emitted when the instance closes the WebSocket connection.

This may happen for example when the user opens DevTools or when the tab is closed.

Issue a command to the remote instance.

method is a string describing the command.

params is an object containing the payload.

sessionId is a string representing the session identifier.

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

• error: a boolean value indicating the success status, as reported by the remote instance;
• response: an object containing either the response (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. The Error object returned contains two additional parameters: request and response which contain the raw massages, useful for debugging purposes. In case of low-level WebSocket errors, the error parameter contains the originating Error object and no response is returned.

Note that the field id mentioned in the Chrome Debugging Protocol specification is managed internally and it is not exposed to the user.

For example:

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

Just a shorthand for:

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

For example:

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

Just a shorthand for:

client.on('<domain>.<event>[.<sessionId>]', callback);

When callback is omitted the event is registered only once and a Promise object is returned. Notice though that in this case the optional sessionId usually passed to callback is not returned.

When callback is provided, it returns a function that can be used to unsubscribe callback from the event, it can be useful when anonymous functions are used as callbacks.

For example:

const unsubscribe = client.Network.requestWillBeSent(params, sessionId) => {
    console.log(params.request.url);
});
unsubscribe();

Close the connection to the remote instance.

callback is executed when the WebSocket is successfully closed.

When callback is omitted a Promise object is returned.

Just a shorthand for:

client.<domain>.<name>

Where <name> can be a command, an event, or a type.

This means that you are trying to use a method or an event that are not present in the protocol descriptor that you are using.

If the protocol is fetched from Chrome directly, then it means that this version of Chrome does not support that feature. The solution is to update it.

If you are using a local or custom version of the protocol, then it means that the version is obsolete. The solution is to provide an up-to-date one, or if you are using the protocol embedded in chrome-remote-interface, make sure to be running the latest version of this module. In case the embedded protocol is obsolete, please file an issue.

See here for more information.

This means that you are providing a custom or local protocol descriptor (CDP({protocol: customProtocol})) which declares Domain.method while the Chrome version that you are using does not support it.

To inspect the currently available protocol descriptor use:

$ chrome-remote-interface inspect

See here for more information.

This happens because the size of /dev/shm is set to 64MB by default in Docker and may not be enough for Chrome to navigate certain web pages.

You can change this value by running your container with, say, --shm-size=256m.

This is thrown by Runtime.evaluate when the browser-side promise gets collected by the Chrome's garbage collector, this happens when the whole JavaScript execution environment is invalidated, e.g., a when page is navigated or reloaded while a promise is still waiting to be resolved.

Here is an example:

$ chrome-remote-interface inspect
>>> Runtime.evaluate({expression: `new Promise(() => {})`, awaitPromise: true})
>>> Page.reload() / then wait several seconds
{ result: {} }
{ error: { code: -32000, message: 'Promise was collected' } }

To fix this, just make sure there are no pending promises before closing, reloading, etc. a page.

Chrome Debugging Protocol which, among the other things, may start and use a bundled version of Chromium instead of the one installed on your system. Use it if its API meets your needs as it would probably be easier to work with.

chrome-remote-interface instead is just a general purpose 1:1 Node.js binding for the Chrome Debugging Protocol. Use it if you need all the power of the raw protocol, e.g., to implement your own high-level API.

See #240 for a more thorough discussion.

• Andrey Sidorov
• Greg Cochard

• Chrome Debugging Protocol
• Chrome Debugging Protocol Google group
• devtools-protocol official repo
• Showcase Chrome Debugging Protocol Clients
• Awesome chrome-devtools