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.
npm install chrome-remote-interface
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
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');
});
This module comes with a REPL interface that can be used to interactively
control Chrome (run with --help
to display the list of available options). It
supports command execution and event binding, see the documentation for
chrome.Domain.method([params], [callback])
and
chrome.Domain.event(callback)
. 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.' }
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 tolocalhost
;port
: Remote Debugging Protocol port. Defaults to9222
;chooseTab
: callback used to determine which remote tab attach to. Takes the array returned byhttp://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:
function (chrome) {}
Emitted when the connection to Chrome is established.
chrome
is an instance of the Chrome
class.
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
.
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 tolocalhost
;port
: Remote Debugging Protocol port. Defaults to9222
.
callback
is executed when the list is correctly received, it gets the
following arguments:
err
: aError
object indicating the success status;tabs
: the array returned byhttp://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);
}
});
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.
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);
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, as reported by Chrome;response
: an object containing either the response sent from Chrome (result
field, iferror === false
) or the indication of the error (error
field, iferror === true
).
Note that the field id
mentioned in the Remote Debugging Protocol
specifications is managed internally and it's not exposed to the user.
Just a shorthand for:
chrome.send('Domain.method', params, callback);
For example:
chrome.Page.navigate({'url': 'https://github.com'});
Just a shorthand for:
chrome.on('Domain.event', callback);
For example:
chrome.Network.requestWillBeSent(console.log);
Close the connection to Chrome.