Skip to content

Commit

Permalink
Rename "tab" to "target" to be more general
Browse files Browse the repository at this point in the history
  • Loading branch information
@cyrus-and
cyrus-and committed Apr 17, 2017
1 parent 7b44534 commit dba3ed8
Show file tree
Hide file tree
Showing 5 changed files with 139 additions and 135 deletions.
54 changes: 28 additions & 26 deletions README.md
View file
Expand Up @@ -167,7 +167,7 @@ Bundled client
This module comes with a bundled client application that can be used to
interactively control a remote instance.

### Tab management
### Target management

The bundled client exposes subcommands to interact with the HTTP frontend
(e.g., [List](#cdplistoptions-callback), [New](#cdpnewoptions-callback), etc.),
Expand Down Expand Up @@ -437,18 +437,18 @@ Connects to a remote instance using the [Chrome Debugging Protocol].
- `host`: HTTP frontend host. Defaults to `localhost`;
- `port`: HTTP frontend port. Defaults to `9222`;
- `secure`: HTTPS/WSS frontend. Defaults to `false`;
- `tab`: determines which tab this client should attach to. The behavior changes
according to the type:
- `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 tab or its numeric index relative to the array;
- a tab `object` like those returned by the `New` and `List` methods;
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 tab list.
`port` are not used to fetch the target list.

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 tab);
same target);
- `protocol`: [Chrome 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*
Expand Down Expand Up @@ -483,7 +483,7 @@ function () {}
Emitted when an instance closes the WebSocket connection.

This may happen for example when the user opens DevTools for the currently
inspected Chrome tab.
inspected Chrome target.

#### Event: 'error'

Expand Down Expand Up @@ -533,7 +533,7 @@ CDP.Protocol(function (err, protocol) {

### CDP.List([options], [callback])

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

`options` is an object with the following optional properties:

Expand All @@ -545,61 +545,63 @@ Request the list of the available open tabs of the remote instance.
following arguments:

- `err`: a `Error` object indicating the success status;
- `tabs`: the array returned by `http://host:port/json/list` containing the tab
list.
- `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:

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

### CDP.New([options], [callback])

Create a new tab in the remote instance.
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`;
- `url`: URL to load in the new tab. Defaults to `about:blank`.
- `url`: URL to load in the new target/tab. Defaults to `about:blank`.

`callback` is executed when the tab is created, it gets the following arguments:
`callback` is executed when the target 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.
- `target`: the object returned by `http://host:port/json/new` containing the
target.

When `callback` is omitted a `Promise` object is returned.

For example:

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

### CDP.Activate([options], [callback])

Activate an open tab of the remote instance.
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`;
- `id`: Tab id. Required, no default.
- `id`: Target id. Required, no default.

`callback` is executed when the response to the activation request is
received. It gets the following arguments:
Expand All @@ -614,21 +616,21 @@ For example:
const CDP = require('chrome-remote-interface');
CDP.Activate({'id': 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, function (err) {
if (!err) {
console.log('success! tab is activated');
console.log('success! target is activated');
}
});
```

### CDP.Close([options], [callback])

Close an open tab of the remote instance.
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`;
- `id`: Tab id. Required, no default.
- `id`: Target id. Required, no default.

`callback` is executed when the response to the close request is received. It
gets the following arguments:
Expand All @@ -643,12 +645,12 @@ For example:
const CDP = require('chrome-remote-interface');
CDP.Close({'id': 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, function (err) {
if (!err) {
console.log('success! tab is closing');
console.log('success! target is closing');
}
});
```

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

### CDP.Version([options], [callback])
Expand Down
30 changes: 15 additions & 15 deletions bin/client.js
View file
Expand Up @@ -32,16 +32,16 @@ function inheritProperties(from, to) {

function inspect(target, args, options) {
options.remote = args.remote;
// otherwise the active tab
// otherwise the active target
if (target) {
if (args.webSocket) {
// by WebSocket URL
options.tab = target;
options.target = target;
} else {
// by tab id
options.tab = function (tabs) {
return tabs.findIndex(function (tab) {
return tab.id === target;
// by target id
options.target = function (targets) {
return targets.findIndex(function (target) {
return target.id === target;
});
};
}
Expand Down Expand Up @@ -186,23 +186,23 @@ function inspect(target, args, options) {
}

function list(options) {
CDP.List(options, function (err, tabs) {
CDP.List(options, function (err, targets) {
if (err) {
console.error(err.toString());
process.exit(1);
}
console.log(toJSON(tabs));
console.log(toJSON(targets));
});
}

function _new(url, options) {
options.url = url;
CDP.New(options, function (err, tab) {
CDP.New(options, function (err, target) {
if (err) {
console.error(err.toString());
process.exit(1);
}
console.log(toJSON(tab));
console.log(toJSON(target));
});
}

Expand Down Expand Up @@ -259,7 +259,7 @@ program
program
.command('inspect [<target>]')
.description('inspect a target (defaults to the first available target)')
.option('-w, --web-socket', 'interpret <target> as a WebSocket URL instead of a tab id')
.option('-w, --web-socket', 'interpret <target> as a WebSocket URL instead of a target id')
.option('-j, --protocol <file.json>', 'Chrome Debugging Protocol descriptor (overrides `--remote`)')
.option('-r, --remote', 'Attempt to fetch the protocol descriptor remotely')
.action(function (target, args) {
Expand All @@ -268,28 +268,28 @@ program

program
.command('list')
.description('list all the available tabs')
.description('list all the available targets/tabs')
.action(function () {
action = list;
});

program
.command('new [<url>]')
.description('create a new tab')
.description('create a new target/tab')
.action(function (url) {
action = _new.bind(null, url);
});

program
.command('activate <id>')
.description('activate a tab by id')
.description('activate a target/tab by id')
.action(function (id) {
action = activate.bind(null, id);
});

program
.command('close <id>')
.description('close a tab by id')
.description('close a target/tab by id')
.action(function (id) {
action = close.bind(null, id);
});
Expand Down
46 changes: 24 additions & 22 deletions lib/chrome.js
View file
Expand Up @@ -14,12 +14,12 @@ class Chrome extends EventEmitter {
constructor(options, notifier) {
super();
// options
const defaultTab = function (tabs) {
const tab = tabs.find((tab) => !!tab.webSocketDebuggerUrl);
if (tab) {
return tab;
const defaultTarget = function (targets) {
const target = targets.find((target) => !!target.webSocketDebuggerUrl);
if (target) {
return target;
} else {
throw new Error ('No inspectable tabs');
throw new Error ('No inspectable targets');
}
};
options = options || {};
Expand All @@ -28,7 +28,9 @@ class Chrome extends EventEmitter {
this.secure = !!(options.secure);
this.protocol = options.protocol;
this.remote = !!(options.remote);
this.tab = options.tab || options.chooseTab || defaultChooseTab;
this.target = options.target ||
/* backward compatibility */ options.tab || options.chooseTab
|| defaultTarget;
// locals
EventEmitter.call(this);
this._notifier = notifier;
Expand Down Expand Up @@ -140,50 +142,50 @@ function fetchProtocol(options) {
});
}

// fetch the WebSocket URL according to 'tab'
// fetch the WebSocket URL according to 'target'
function fetchDebuggerURL(options) {
const chrome = this;
return new Promise(function (fulfill, reject) {
// note: when DevTools are open or another WebSocket is connected to a
// given tab the 'webSocketDebuggerUrl' field is not available
const invalidTabError = function (tab) {
return new Error('Invalid tab ' + JSON.stringify(tab, null, 4));
// given target the 'webSocketDebuggerUrl' field is not available
const invalidTargetError = function (target) {
return new Error('Invalid target ' + JSON.stringify(target, null, 4));
};
let url;
switch (typeof chrome.tab) {
switch (typeof chrome.target) {
case 'string':
// a WebSocket URL is specified by the user (e.g., node-inspector)
fulfill(chrome.tab);
fulfill(chrome.target);
break;
case 'object':
// a tab object is specified by the user
url = chrome.tab.webSocketDebuggerUrl;
// a target object is specified by the user
url = chrome.target.webSocketDebuggerUrl;
if (url) {
fulfill(url);
} else {
reject(invalidTabError(chrome.tab));
reject(invalidTargetError(chrome.target));
}
break;
case 'function':
// a function is specified by the user
devtools.List(options).then(function (tabs) {
const result = chrome.tab(tabs);
devtools.List(options).then(function (targets) {
const result = chrome.target(targets);
if (typeof result === 'number') {
return tabs[result];
return targets[result];
} else {
return result;
}
}).then(function (tab) {
url = (tab || {}).webSocketDebuggerUrl;
}).then(function (target) {
url = (target || {}).webSocketDebuggerUrl;
if (url) {
fulfill(url);
} else {
reject(invalidTabError(tab));
reject(invalidTargetError(target));
}
}).catch(reject);
break;
default:
reject(new Error('Invalid tab argument "' + chrome.tab + '"'));
reject(new Error('Invalid target argument "' + chrome.target + '"'));
}
});
}
Expand Down

0 comments on commit dba3ed8

Please sign in to comment.