opal 1.6.1 → 1.7.0

data/lib/opal/cli_runners/node_modules/chrome-remote-interface/README.md

@@ -1,5 +1,7 @@
-chrome-remote-interface    [![Build Status](https://travis-ci.org/cyrus-and/chrome-remote-interface.svg?branch=master)](https://travis-ci.org/cyrus-and/chrome-remote-interface)
-=======================
+# chrome-remote-interface [![Build Status][]][travis]
+
+[Build Status]: https://app.travis-ci.com/cyrus-and/chrome-remote-interface.svg?branch=master
+[travis]: https://app.travis-ci.com/cyrus-and/chrome-remote-interface
 
 [Chrome Debugging Protocol] interface that helps to instrument Chrome (or any
 other suitable [implementation](#implementations)) by providing a simple
@@ -10,55 +12,54 @@ This module is one of the many [third-party protocol clients][3rd-party].
 
 [3rd-party]: https://developer.chrome.com/devtools/docs/debugging-clients#chrome-remote-interface
 
-Sample API usage
-----------------
+## Sample API usage
 
 The following snippet loads `https://github.com` and dumps every request made:
 
 ```js
 const CDP = require('chrome-remote-interface');
 
-CDP((client) => {
-    // extract domains
-    const {Network, Page} = client;
-    // setup handlers
-    Network.requestWillBeSent((params) => {
-        console.log(params.request.url);
-    });
-    Page.loadEventFired(() => {
-        client.close();
-    });
-    // enable events then start!
-    Promise.all([
-        Network.enable(),
-        Page.enable()
-    ]).then(() => {
-        return Page.navigate({url: 'https://github.com'});
-    }).catch((err) => {
+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);
-        client.close();
-    });
-}).on('error', (err) => {
-    // cannot connect to the remote endpoint
-    console.error(err);
-});
+    } finally {
+        if (client) {
+            await client.close();
+        }
+    }
+}
+
+example();
 ```
 
-Find more examples in the [wiki], in particular notice how the above can be
-rewritten using the [`async`/`await`][async-await-example] primitives.
+Find more examples in the [wiki]. You may also want to take a look at the [FAQ].
 
 [wiki]: https://github.com/cyrus-and/chrome-remote-interface/wiki
 [async-await-example]: https://github.com/cyrus-and/chrome-remote-interface/wiki/Async-await-example
+[FAQ]: https://github.com/cyrus-and/chrome-remote-interface#faq
 
-Installation
-------------
+## Installation
 
     npm install chrome-remote-interface
 
 Install globally (`-g`) to just use the [bundled client](#bundled-client).
 
-Implementations
----------------
+## Implementations
 
 This module should work with every application implementing the
 [Chrome Debugging Protocol]. In particular, it has been tested against the
@@ -66,16 +67,22 @@ following implementations:
 
 Implementation             | Protocol version   | [Protocol] | [List] | [New] | [Activate] | [Close] | [Version]
 ---------------------------|--------------------|------------|--------|-------|------------|---------|-----------
-[Google Chrome][1.1]       | [tip-of-tree][1.2] | yes        | yes    | yes   | yes        | yes     | yes
-[Microsoft Edge][2.1]      | [*partial*][2.2]   | yes        | yes    | no    | no         | no      | yes
+[Chrome][1.1]              | [tip-of-tree][1.2] | yes¹       | yes    | yes   | yes        | yes     | yes
+[Opera][2.1]               | [tip-of-tree][2.2] | yes        | yes    | yes   | yes        | yes     | yes
 [Node.js][3.1] ([v6.3.0]+) | [node][3.2]        | yes        | no     | no    | no         | no      | yes
 [Safari (iOS)][4.1]        | [*partial*][4.2]   | no         | yes    | no    | no         | no      | no
+[Edge][5.1]                | [*partial*][5.2]   | yes        | yes    | no    | no         | no      | yes
+[Firefox (Nightly)][6.1]   | [*partial*][6.2]   | yes        | yes    | no    | yes        | yes     | yes
+
+¹ Not available on [Chrome for Android][chrome-mobile-protocol], hence a local version of the protocol must be used.
+
+[chrome-mobile-protocol]: https://bugs.chromium.org/p/chromium/issues/detail?id=824626#c4
 
 [1.1]: #chromechromium
 [1.2]: https://chromedevtools.github.io/devtools-protocol/tot/
 
-[2.1]: #edge
-[2.2]: https://github.com/Microsoft/edge-diagnostics-adapter/wiki/Supported-features-and-API
+[2.1]: #opera
+[2.2]: https://chromedevtools.github.io/devtools-protocol/tot/
 
 [3.1]: #nodejs
 [3.2]: https://chromedevtools.github.io/devtools-protocol/v8/
@@ -83,6 +90,12 @@ Implementation             | Protocol version   | [Protocol] | [List] | [New] |
 [4.1]: #safari-ios
 [4.2]: http://trac.webkit.org/browser/trunk/Source/JavaScriptCore/inspector/protocol
 
+[5.1]: #edge
+[5.2]: https://docs.microsoft.com/en-us/microsoft-edge/devtools-protocol/0.1/domains/
+
+[6.1]: #firefox-nightly
+[6.2]: https://firefox-source-docs.mozilla.org/remote/index.html
+
 [v6.3.0]: https://nodejs.org/en/blog/release/v6.3.0/
 
 [Protocol]: #cdpprotocoloptions-callback
@@ -96,8 +109,7 @@ The meaning of *target* varies according to the implementation, for example,
 each Chrome tab represents a target whereas for Node.js a target is the
 currently inspected script.
 
-Setup
------
+## Setup
 
 An instance of either Chrome itself or another implementation needs to be
 running on a known port in order to use this module (defaults to
@@ -123,6 +135,9 @@ Plug the device and enable the [port forwarding][adb], for example:
 
     adb forward tcp:9222 localabstract:chrome_devtools_remote
 
+Note that in Android, Chrome does not have its own protocol available, a local
+version must be used. See [here](#chrome-debugging-protocol-versions) for more information.
+
 [adb]: https://developer.chrome.com/devtools/docs/remote-debugging-legacy
 
 ##### WebView
@@ -139,11 +154,11 @@ Finally, port forwarding can be enabled as follows:
 
 [webview]: https://developers.google.com/web/tools/chrome-devtools/remote-debugging/webviews#configure_webviews_for_debugging
 
-### Edge
+### Opera
 
-Install and run the [Edge Diagnostics Adapter][edge-adapter].
+Start Opera with the `--remote-debugging-port` option, for example:
 
-[edge-adapter]: https://github.com/Microsoft/edge-diagnostics-adapter
+    opera --remote-debugging-port=9222
 
 ### Node.js
 
@@ -153,12 +168,31 @@ Start Node.js with the `--inspect` option, for example:
 
 ### Safari (iOS)
 
-Install and run the [iOS WebKit Debug Proxy][iwdp].
+Install and run the [iOS WebKit Debug Proxy][iwdp]. Then use it with the `local`
+option set to `true` to use the local version of the protocol or pass a custom
+descriptor upon connection (`protocol` option).
 
 [iwdp]: https://github.com/google/ios-webkit-debug-proxy
 
-Bundled client
---------------
+### Edge
+
+Start Edge with the `--devtools-server-port` option, for example:
+
+    MicrosoftEdge.exe --devtools-server-port 9222 about:blank
+
+Please find more information [here][edge-devtools].
+
+[edge-devtools]: https://docs.microsoft.com/en-us/microsoft-edge/devtools-protocol/
+
+### Firefox (Nightly)
+
+Start Firefox with the `--remote-debugging-port` option, for example:
+
+    firefox --remote-debugging-port 9222
+
+Bear in mind that this is an experimental feature of Firefox.
+
+## Bundled client
 
 This module comes with a bundled client application that can be used to
 interactively control a remote instance.
@@ -171,7 +205,7 @@ run with `--help` to display the list of available options.
 
 Here are some examples:
 
-```javascript
+```js
 $ chrome-remote-interface new 'http://example.com'
 {
     "description": "",
@@ -188,67 +222,37 @@ $ chrome-remote-interface close 'b049bb56-de7d-424c-a331-6ae44cf7ae01'
 
 ### Inspection
 
-Using the `inspect` subcommand it is possible to
-perform [command execution](#clientdomainmethodparams-callback)
-and [event binding](#clientdomaineventcallback) 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.
-
-Remember that the REPL interface provides completion.
+Using the `inspect` subcommand it is possible to perform [command execution](#clientdomainmethodparams-callback)
+and [event binding](#clientdomaineventcallback) in a REPL fashion that provides completion.
 
 Here is a sample session:
 
-```javascript
+```js
 $ 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 } }
+{ result: { type: 'string', value: 'about:blank' } }
 >>> Page.enable()
-{ result: {} }
->>> Page.loadEventFired() // registered
-{ 'Page.loadEventFired': true }
->>> Page.loadEventFired() // unregistered
-{ 'Page.loadEventFired': false }
->>> Page.loadEventFired() // registered
-{ 'Page.loadEventFired': true }
+{}
+>>> Page.loadEventFired(console.log)
+[Function]
 >>> Page.navigate({url: 'https://github.com'})
-{ result: { frameId: '28677.1' } }
-{ 'Page.loadEventFired': { timestamp: 21385.383076 } }
+{ frameId: 'E1657E22F06E6E0BE13DFA8130C20298',
+  loaderId: '439236ADE39978F98C20E8939A32D3A5' }
+>>> { timestamp: 7454.721299 } // from Page.loadEventFired
 >>> Runtime.evaluate({expression: 'window.location.toString()'})
-{ result:
-   { result: { type: 'string', value: 'https://github.com/' },
-     wasThrown: false } }
+{ result: { type: 'string', value: 'https://github.com/' } }
 ```
 
-#### Event filtering
+Additionally there are some custom commands available:
 
-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:
+```js
+>>> .help
+[...]
+.reset    Remove all the registered event handlers
+.target   Display the current target
+```
 
-```javascript
-$ 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
-----------------------
+## Embedded documentation
 
 In both the REPL and the regular API every object of the protocol is *decorated*
 with the meta information found within the descriptor. In addition The
@@ -257,7 +261,7 @@ with the meta information found within the descriptor. In addition The
 
 For example to learn how to call `Page.navigate`:
 
-```javascript
+```js
 >>> Page.navigate
 { [Function]
   category: 'command',
@@ -273,7 +277,7 @@ For example to learn how to call `Page.navigate`:
 
 To learn about the parameters returned by the `Network.requestWillBeSent` event:
 
-```javascript
+```js
 >>> Network.requestWillBeSent
 { [Function]
   category: 'event',
@@ -309,7 +313,7 @@ To learn about the parameters returned by the `Network.requestWillBeSent` event:
 To inspect the `Network.Request` (note that unlike commands and events, types
 are named in upper camel case) type:
 
-```javascript
+```js
 >>> Network.Request
 { category: 'type',
   id: 'Request',
@@ -333,35 +337,28 @@ are named in upper camel case) type:
         description: 'Priority of the resource request at the time request is sent.' } } }
 ```
 
-Chrome Debugging Protocol versions
-----------------------------------
-
-`chrome-remote-interface` uses the [local version] of the protocol descriptor by
-default. This file is manually updated from time to time using
-`scripts/update-protocol.sh` and pushed to this repository.
+## Chrome Debugging Protocol versions
 
-This behavior can be changed by setting the `remote` option to `true`
-upon [connection](#cdpoptions-callback), in which case the remote instance is
-*asked* to provide its own protocol descriptor.
+By default `chrome-remote-interface` *asks* the remote instance to provide its
+own protocol.
 
-Chrome < 60.0.3097.0 is not able to do that, so in that case the protocol
-descriptor is fetched from the source repository.
+This behavior can be changed by setting the `local` option to `true`
+upon [connection](#cdpoptions-callback), in which case the [local version] of
+the protocol descriptor is used. This 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:
+To further override the above behavior there are basically two options:
 
 - pass a custom protocol descriptor upon [connection](#cdpoptions-callback)
   (`protocol` option);
 
 - use the *raw* version of the [commands](#clientsendmethod-params-callback)
-  and [events](#event-domainmethod) interface;
-
-- update the local copy with `scripts/update-protocol.sh` (not present when
-  fetched with `npm install`).
+  and [events](#event-domainmethod) interface to use bleeding-edge features that
+  do not appear in the [local version] of the protocol descriptor;
 
 [local version]: lib/protocol.json
 
-Browser usage
--------------
+## Browser usage
 
 This module is able to run within a web context, with obvious limitations
 though, namely external HTTP requests
@@ -385,10 +382,6 @@ It just works, simply require this module:
 const CDP = require('chrome-remote-interface');
 ```
 
-To use a non-minified version manually run webpack with:
-
-    DEBUG=true npm run webpack
-
 ### Using *vanilla* JavaScript
 
 To generate a JavaScript file that can be used with a `<script>` element:
@@ -398,7 +391,6 @@ To generate a JavaScript file that can be used with a `<script>` element:
 2. manually run webpack with:
 
         TARGET=var npm run webpack
-        TARGET=var DEBUG=true npm run webpack
 
 3. use as:
 
@@ -408,9 +400,20 @@ To generate a JavaScript file that can be used with a `<script>` element:
     </script>
     <script src="chrome-remote-interface.js"></script>
     ```
+## TypeScript Support
 
-API
----
+[TypeScript][] definitions are kindly provided by [Khairul Azhar Kasmiran][] and [Seth Westphal][], and can be installed from [DefinitelyTyped][]:
+
+```
+npm install --save-dev @types/chrome-remote-interface
+```
+
+[TypeScript]: https://www.typescriptlang.org/
+[Khairul Azhar Kasmiran]: https://github.com/kazarmy
+[Seth Westphal]: https://github.com/westy92
+[DefinitelyTyped]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/chrome-remote-interface
+
+## API
 
 The API consists of three parts:
 
@@ -431,6 +434,9 @@ 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`;
+- `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:
 
@@ -446,12 +452,14 @@ Connects to a remote instance using the [Chrome Debugging Protocol].
   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 `remote` option;
-- `remote`: a boolean indicating whether the protocol must be fetched *remotely*
+  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.
+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
@@ -462,7 +470,7 @@ The `EventEmitter` supports the following events:
 
 #### Event: 'connect'
 
-```javascript
+```js
 function (client) {}
 ```
 
@@ -472,7 +480,7 @@ Emitted when the connection to the WebSocket is established.
 
 #### Event: 'error'
 
-```javascript
+```js
 function (err) {}
 ```
 
@@ -490,28 +498,27 @@ Fetch the [Chrome Debugging Protocol] descriptor.
 - `host`: HTTP frontend host. Defaults to `localhost`;
 - `port`: HTTP frontend port. Defaults to `9222`;
 - `secure`: HTTPS/WSS frontend. Defaults to `false`;
-- `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`.
+- `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`: 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 [Chrome Debugging Protocol] descriptor.
+- `protocol`: the [Chrome Debugging Protocol] descriptor.
 
 When `callback` is omitted a `Promise` object is returned.
 
 For example:
 
-```javascript
+```js
 const CDP = require('chrome-remote-interface');
-CDP.Protocol(function (err, protocol) {
+CDP.Protocol((err, protocol) => {
     if (!err) {
-        console.log(JSON.stringify(protocol.descriptor, null, 4));
+        console.log(JSON.stringify(protocol, null, 4));
     }
 });
 ```
@@ -524,7 +531,10 @@ Request the list of the available open targets/tabs of the remote instance.
 
 - `host`: HTTP frontend host. Defaults to `localhost`;
 - `port`: HTTP frontend port. Defaults to `9222`;
-- `secure`: HTTPS/WSS frontend. Defaults to `false`.
+- `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:
@@ -537,9 +547,9 @@ When `callback` is omitted a `Promise` object is returned.
 
 For example:
 
-```javascript
+```js
 const CDP = require('chrome-remote-interface');
-CDP.List(function (err, targets) {
+CDP.List((err, targets) => {
     if (!err) {
         console.log(targets);
     }
@@ -555,6 +565,9 @@ Create a new target/tab in the remote instance.
 - `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
@@ -568,9 +581,9 @@ When `callback` is omitted a `Promise` object is returned.
 
 For example:
 
-```javascript
+```js
 const CDP = require('chrome-remote-interface');
-CDP.New(function (err, target) {
+CDP.New((err, target) => {
     if (!err) {
         console.log(target);
     }
@@ -586,6 +599,9 @@ Activate an open target/tab of the remote instance.
 - `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
@@ -597,9 +613,9 @@ When `callback` is omitted a `Promise` object is returned.
 
 For example:
 
-```javascript
+```js
 const CDP = require('chrome-remote-interface');
-CDP.Activate({'id': 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, function (err) {
+CDP.Activate({id: 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, (err) => {
     if (!err) {
         console.log('target is activated');
     }
@@ -615,6 +631,9 @@ Close an open target/tab of the remote instance.
 - `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
@@ -626,9 +645,9 @@ When `callback` is omitted a `Promise` object is returned.
 
 For example:
 
-```javascript
+```js
 const CDP = require('chrome-remote-interface');
-CDP.Close({'id': 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, function (err) {
+CDP.Close({id: 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, (err) => {
     if (!err) {
         console.log('target is closing');
     }
@@ -646,7 +665,10 @@ Request version information from the remote instance.
 
 - `host`: HTTP frontend host. Defaults to `localhost`;
 - `port`: HTTP frontend port. Defaults to `9222`;
-- `secure`: HTTPS/WSS frontend. Defaults to `false`.
+- `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:
@@ -659,9 +681,9 @@ When `callback` is omitted a `Promise` object is returned.
 
 For example:
 
-```javascript
+```js
 const CDP = require('chrome-remote-interface');
-CDP.Version(function (err, info) {
+CDP.Version((err, info) => {
     if (!err) {
         console.log(info);
     }
@@ -672,7 +694,7 @@ CDP.Version(function (err, info) {
 
 #### Event: 'event'
 
-```javascript
+```js
 function (message) {}
 ```
 
@@ -682,14 +704,15 @@ Emitted when the remote instance sends any notification through the WebSocket.
 
 - `method`: a string describing the notification (e.g.,
   `'Network.requestWillBeSent'`);
-- `params`: an object containing the payload.
+- `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:
 
-```javascript
-client.on('event', function (message) {
+```js
+client.on('event', (message) => {
     if (message.method === 'Network.requestWillBeSent') {
         console.log(message.params);
     }
@@ -698,8 +721,8 @@ client.on('event', function (message) {
 
 #### Event: '`<domain>`.`<method>`'
 
-```javascript
-function (params) {}
+```js
+function (params, sessionId) {}
 ```
 
 Emitted when the remote instance sends a notification for `<domain>.<method>`
@@ -707,16 +730,36 @@ 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'`](#event-event)), for example:
 
-```javascript
+```js
 client.on('Network.requestWillBeSent', console.log);
 ```
 
+Additionally, the equivalent `<domain>.on('<method>', ...)` syntax is available, for example:
+
+```js
+client.Network.on('requestWillBeSent', console.log);
+```
+
+#### Event: '`<domain>`.`<method>`.`<sessionId>`'
+
+```js
+function (params, sessionId) {}
+```
+
+Equivalent to the following but only for those events belonging to the given `session`:
+
+```js
+client.on('<domain>.<event>', callback);
+```
+
 #### Event: 'ready'
 
-```javascript
+```js
 function () {}
 ```
 
@@ -733,11 +776,11 @@ 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:
 
-```javascript
+```js
 client.Network.enable();
 client.Page.enable();
-client.once('ready', function () {
-    client.Page.navigate({'url': 'https://github.com'});
+client.once('ready', () => {
+    client.Page.navigate({url: 'https://github.com'});
 });
 ```
 
@@ -748,7 +791,7 @@ client.
 
 #### Event: 'disconnect'
 
-```javascript
+```js
 function () {}
 ```
 
@@ -757,7 +800,7 @@ Emitted when the instance closes the WebSocket connection.
 This may happen for example when the user opens DevTools or when the tab is
 closed.
 
-#### client.send(method, [params], [callback])
+#### client.send(method, [params], [sessionId], [callback])
 
 Issue a command to the remote instance.
 
@@ -765,6 +808,8 @@ Issue a command to the remote instance.
 
 `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:
 
@@ -775,46 +820,57 @@ command, it gets the following arguments:
   === true`).
 
 When `callback` is omitted a `Promise` object is returned instead, with the
-fulfilled/rejected states implemented according to the `error` parameter.
+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:
 
-```javascript
-client.send('Page.navigate', {'url': 'https://github.com'}, console.log);
+```js
+client.send('Page.navigate', {url: 'https://github.com'}, console.log);
 ```
 
-#### client.`<domain>`.`<method>`([params], [callback])
+#### client.`<domain>`.`<method>`([params], [sessionId], [callback])
 
 Just a shorthand for:
 
-```javascript
-client.send('<domain>.<method>', params, callback);
+```js
+client.send('<domain>.<method>', params, sessionId, callback);
 ```
 
 For example:
 
-```javascript
-client.Page.navigate({'url': 'https://github.com'}, console.log);
+```js
+client.Page.navigate({url: 'https://github.com'}, console.log);
 ```
 
-#### client.`<domain>`.`<event>`([callback])
+#### client.`<domain>`.`<event>`([sessionId], [callback])
 
 Just a shorthand for:
 
-```javascript
-client.on('<domain>.<event>', callback);
+```js
+client.on('<domain>.<event>[.<sessionId>]', callback);
 ```
 
-The only difference is that when `callback` is omitted the event is registered
-only once and a `Promise` object is returned.
+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:
 
-```javascript
-client.Network.requestWillBeSent(console.log);
+```js
+const unsubscribe = client.Network.requestWillBeSent((params, sessionId) => {
+    console.log(params.request.url);
+});
+unsubscribe();
 ```
 
 #### client.close([callback])
@@ -825,14 +881,98 @@ Close the connection to the remote instance.
 
 When `callback` is omitted a `Promise` object is returned.
 
-Contributors
-------------
+#### client['`<domain>`.`<name>`']
+
+Just a shorthand for:
+
+```js
+client.<domain>.<name>
+```
+
+Where `<name>` can be a command, an event, or a type.
+
+## FAQ
+
+### Invoking `Domain.methodOrEvent` I obtain `Domain.methodOrEvent is not a function`
+
+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](https://github.com/cyrus-and/chrome-remote-interface/issues/new).
+
+See [here](#chrome-debugging-protocol-versions) for more information.
+
+### Invoking `Domain.method` I obtain `Domain.method wasn't found`
+
+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](#chrome-debugging-protocol-versions) for more information.
+
+### Why my program stalls or behave unexpectedly if I run Chrome in a Docker container?
+
+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`.
+
+### Using `Runtime.evaluate` with `awaitPromise: true` I sometimes obtain `Error: Promise was collected`
+
+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.
+
+### How does this compare to Puppeteer?
+
+[Puppeteer] is an additional high-level API built upon the [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.
+
+[Puppeteer]: https://github.com/GoogleChrome/puppeteer
+[#240]: https://github.com/cyrus-and/chrome-remote-interface/issues/240
+
+## Contributors
 
 - [Andrey Sidorov](https://github.com/sidorares)
 - [Greg Cochard](https://github.com/gcochard)
 
-Resources
----------
+## Resources
 
 - [Chrome Debugging Protocol]
 - [Chrome Debugging Protocol Google group](https://groups.google.com/forum/#!forum/chrome-debugging-protocol)