chrome-remote-interface - npm Package Compare versions

Comparing version 0.15.0 to 0.15.1

bin/client.js

@@ -58,6 +58,31 @@ #!/usr/bin/env node
 
-        // make the history persistent
-        const history_file = path.join(process.env.HOME, '.cri_history');
-        require('repl.history')(chromeRepl, history_file);
+        const historyFile = path.join(process.env.HOME, '.cri_history');
+        const historySize = 10000;
 
+        function loadHistory() {
+            // attempt to open the history file
+            var fd;
+            try {
+                fd = fs.openSync(historyFile, 'r');
+            } catch (err) {
+                return; // no history file present
+            }
+            // populate the REPL history
+            fs.readFileSync(fd, 'utf8')
+                .split('\n')
+                .filter(function (entry) {
+                    return entry.trim();
+                })
+                .reverse() // to be compatible with repl.history files
+                .forEach(function (entry) {
+                    chromeRepl.history.push(entry);
+                });
+        }
+
+        function saveHistory() {
+            // only store the last chunk
+            const entries = chromeRepl.history.slice(0, historySize).reverse().join('\n');
+            fs.writeFileSync(historyFile, entries + '\n');
+        }
+
         function overridePrompt(string) {
@@ -116,2 +141,5 @@ // hack to get rid of the prompt (clean line and reposition cursor)
 
+        // enable history
+        loadHistory();
+
         // disconnect on exit
@@ -121,2 +149,3 @@ chromeRepl.on('exit', function () {
             chrome.close();
+            saveHistory();
         });
@@ -127,2 +156,3 @@
             console.error('Disconnected.');
+            saveHistory();
             process.exit(1);
@@ -229,3 +259,3 @@ });
     .option('-w, --web-socket', 'interpret <target> as a WebSocket URL instead of a tab id')
-    .option('-j, --protocol <file.json>', 'Remote Debugging Protocol descriptor (overrides `--remote`)')
+    .option('-j, --protocol <file.json>', 'Chrome Debugging Protocol descriptor (overrides `--remote`)')
     .option('-r, --remote', 'Attempt to fetch the protocol descriptor remotely')
@@ -232,0 +262,0 @@ .action(function (target, args) {

package.json

@@ -9,6 +9,6 @@ {
     ],
-    "description": "Chrome Remote Debugging Protocol interface",
-    "keywords": ["chrome", "remote", "debug", "interface"],
+    "description": "Chrome Debugging Protocol interface",
+    "keywords": ["chrome", "debug", "protocol", "remote", "interface"],
     "homepage": "https://github.com/cyrus-and/chrome-remote-interface",
-    "version": "0.15.0",
+    "version": "0.15.1",
     "repository": {
@@ -26,4 +26,3 @@ "type": "git",
         "ws": "1.x.x",
-        "commander": "2.1.x",
-        "repl.history": "0.1.x"
+        "commander": "2.1.x"
     },
@@ -30,0 +29,0 @@ "files": [

README.md

 chrome-remote-interface
 =======================
 
-[Remote Debugging Protocol][rdp] 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.
+[Chrome Debugging Protocol] interface that helps to instrument Chrome (or any
+other suitable [implementation](#implementations)) by providing a simple
+abstraction of commands and notifications using a straightforward JavaScript
+API.
 
-`chrome-remote-interface` is listed among
-[third-party Chrome debugging protocol clients][clients-cri].
+This module is one of the many [third-party protocol clients][3rd-party].
 
-This module should work with every application implementing the Chrome [Remote
-Debugging Protocol][rdp]. In particular, it has been tested against the
-following implementations:
+[3rd-party]: https://developer.chrome.com/devtools/docs/debugging-clients#chrome-remote-interface
 
-[clients-cri]: https://developer.chrome.com/devtools/docs/debugging-clients#chrome-remote-interface
-
-Implementation        | Notes
-----------------------|------
-[Google Chrome][1.1]  | native support; enable [port forwarding][1.2] in Chrome for Android
-[Microsoft Edge][2.1] | via the [Edge Diagnostics Adapter][2.2]
-[Node.js][3.1]        | via [`--inspect`][3.2] (with `--port 9229`) or via [node-inspector][3.3] (by connecting to `ws://127.0.0.1:8080/?port=5858` by default)
-
-[1.1]: https://www.chromium.org/
-[1.2]: https://developer.chrome.com/devtools/docs/remote-debugging-legacy
-[2.1]: https://www.microsoft.com/windows/microsoft-edge
-[2.2]: https://github.com/Microsoft/edge-diagnostics-adapter
-[3.1]: https://nodejs.org/
-[3.2]: https://chromedevtools.github.io/debugger-protocol-viewer/v8/
-[3.3]: https://github.com/node-inspector/node-inspector
-
-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][rdp], for example:
-
-    google-chrome --remote-debugging-port=9222
-
 Sample API usage
@@ -68,2 +37,73 @@ ----------------
 
+Installation
+------------
+
+    npm install chrome-remote-interface
+
+Install globally (`-g`) to just use the [bundled client](#bundled-client).
+
+Implementations
+---------------
+
+This module should work with every application implementing the
+[Chrome Debugging Protocol]. In particular, it has been tested against the
+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
+[Node.js][3.1] ([v6.3.0]+) | [node][3.2]        | yes        | no     | no    | no         | no      | yes
+
+[1.1]: https://www.chromium.org/
+[1.2]: https://chromedevtools.github.io/debugger-protocol-viewer/tot/
+[2.1]: https://www.microsoft.com/windows/microsoft-edge
+[2.2]: https://github.com/Microsoft/edge-diagnostics-adapter/wiki/Supported-features-and-API
+[3.1]: https://nodejs.org/
+[3.2]: https://chromedevtools.github.io/debugger-protocol-viewer/v8/
+
+[v6.3.0]: https://nodejs.org/en/blog/release/v6.3.0/
+
+[Protocol]: #moduleprotocoloptions-callback
+[List]: #modulelistoptions-callback
+[New]: #modulenewoptions-callback
+[Activate]: #moduleactivateoptions-callback
+[Close]: #modulecloseoptions-callback
+[Version]: #moduleversionoptions-callback
+
+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
+`localhost:9222`).
+
+### Chrome/Chromium
+
+#### Desktop
+
+Start Chrome with the `--remote-debugging-port` option, for example:
+
+    google-chrome --remote-debugging-port=9222
+
+#### Android
+
+Plug the device and enable the [port forwarding][adb], for example:
+
+    adb forward tcp:9222 localabstract:chrome_devtools_remote
+
+[adb]: https://developer.chrome.com/devtools/docs/remote-debugging-legacy
+
+### Edge
+
+Install and run the [Edge Diagnostics Adapter][edge-adapter].
+
+[edge-adapter]: https://github.com/Microsoft/edge-diagnostics-adapter
+
+### Node.js
+
+Start Node.js with the `--inspect` option, for example:
+
+    node --inspect=9222 script.js
+
 Bundled client
@@ -73,3 +113,3 @@ --------------
 This module comes with a bundled client application that can be used to
-interactively control Chrome.
+interactively control a remote instance.
 
@@ -99,10 +139,12 @@ ### Tab management
 
-Using the `inspect` subcommand it is possible to perform [command
-execution](#chromedomainmethodparams-callback) and [event
-binding](#chromedomaineventcallback) 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.
+Using the `inspect` subcommand it is possible to
+perform [command execution](#chromedomainmethodparams-callback)
+and [event binding](#chromedomaineventcallback) 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.
+
 Here is a sample session:
@@ -160,9 +202,8 @@
 
-In both the REPL and the regular API every object of the protocol is
-*decorated* with the information available through the [Remote Debugging
-Protocol][rdp]. The `category` field determines if the member is a `command`,
-an `event` or a `type`.
+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
+`category` field is added, which determines if the member is a `command`, an
+`event` or a `type`.
 
-Remember that the REPL interface provides completion. For example to learn how
-to call `Page.navigate`:
+For example to learn how to call `Page.navigate`:
 
@@ -217,2 +258,3 @@ ```javascript
 ```
+
 To inspect the `Network.Request` (note that unlike commands and events, types
@@ -245,25 +287,30 @@ are named in upper camel case) type:
 
-Remote Debugging Protocol versions
+Chrome Debugging Protocol versions
 ----------------------------------
 
-Currently it is not possible to fetch the protocol descriptor
-([`protocol.json`][local-json]) directly from the instrumented Chrome instance
-(see [#10][issue-10]). Rather, that file can be fetched from the proper [source
-repository][remote-json] at every connection. By default, the [local
-version][local-json] is used. That file is manually updated from time to time
-using `scripts/update-protocol.sh` and pushed to this repository.
+`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.
 
+This behavior can be changed by setting the `remote` option to `true`
+upon [connection](#moduleoptions-callback), in which case the remote instance is
+*asked* to provide its own protocol descriptor.
+
+Currently Chrome is not able to do that (see [#10]), so the protocol descriptor
+is fetched from the proper [source repository].
+
 To override the above behavior there are basically three options:
 
-1. pass a custom protocol descriptor upon [connection](#moduleoptions-callback);
+- pass a custom protocol descriptor upon [connection](#moduleoptions-callback)
+  (`protocol` option);
 
-2. use the *raw* version of the [commands](#chromesendmethod-params-callback)
-   and [events](#event-method) interface;
+- use the *raw* version of the [commands](#chromesendmethod-params-callback)
+  and [events](#event-method) interface;
 
-3. update the local copy with `scripts/update-protocol.sh` (not present when
-   fetched with `npm install`).
+- update the local copy with `scripts/update-protocol.sh` (not present when
+  fetched with `npm install`).
 
-[issue-10]: https://github.com/cyrus-and/chrome-remote-interface/issues/10
-[local-json]: lib/protocol.json
-[remote-json]: https://chromium.googlesource.com/chromium/src/+/master/third_party/WebKit/Source/
+[local version]: lib/protocol.json
+[#10]: https://github.com/cyrus-and/chrome-remote-interface/issues/10
+[source repository]: https://chromium.googlesource.com/chromium/src/+/master/third_party/WebKit/Source/
 
@@ -275,4 +322,3 @@ API
 
-Connects to a remote instance of Chrome using the [Remote Debugging
-Protocol][rdp].
+Connects to a remote instance using the [Chrome Debugging Protocol].
 
@@ -294,4 +340,4 @@ `options` is an object with the following optional properties:
   (tabs) { return 0; }`);
-- `protocol`: [Remote Debugging Protocol][rdp] descriptor object. Defaults to
-  use the protocol chosen according to the `remote` option;
+- `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*
@@ -314,3 +360,3 @@ or if the local version must be used. It has no effect if the `protocol`
 
-Emitted when the connection to Chrome is established.
+Emitted when the connection to the WebSocket is established.
 
@@ -325,5 +371,7 @@ `chrome` is an instance of the `Chrome` class.
 
-Emitted when Chrome closes the connection, e.g., if the user opens the DevTools
-for the currently inspected tab.
+Emitted when an instance closes the WebSocket connection.
 
+This may happen for example when the user opens DevTools for the currently
+inspected Chrome tab.
+
 #### Event: 'error'
@@ -335,4 +383,4 @@
 
-Emitted if `http://host:port/json` can't be reached or if it's not possible to
-connect to Chrome's remote debugging WebSocket.
+Emitted when `http://host:port/json` cannot be reached or if it is not possible
+to connect to the WebSocket.
 
@@ -343,3 +391,3 @@ `err` is an instance of `Error`.
 
-Fetch the [Remote Debugging Protocol][rdp] descriptor.
+Fetch the [Chrome Debugging Protocol] descriptor.
 
@@ -350,5 +398,5 @@ `options` is an object with the following optional properties:
 - `port`: HTTP frontend port. Defaults to `9222`;
-- `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`.
+- `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`.
 
@@ -362,3 +410,3 @@ `callback` is executed when the protocol is fetched, it gets the following
      remote version or not (due to user choice or error);
-   - `descriptor`: the [Remote Debugging Protocol][rdp] descriptor.
+   - `descriptor`: the [Chrome Debugging Protocol] descriptor.
 
@@ -380,3 +428,3 @@ When `callback` is omitted a `Promise` object is returned.
 
-Request the list of the available open tabs of the remote Chrome instance.
+Request the list of the available open tabs of the remote instance.
 
@@ -410,3 +458,3 @@ `options` is an object with the following optional properties:
 
-Create a new tab in the remote Chrome instance.
+Create a new tab in the remote instance.
 
@@ -419,4 +467,3 @@ `options` is an object with the following optional properties:
 
-`callback` is executed when the tab is created, it gets the
-following arguments:
+`callback` is executed when the tab is created, it gets the following arguments:
 
@@ -469,3 +516,3 @@ - `err`: a `Error` object indicating the success status;
 
-Close an open tab of the remote Chrome instance.
+Close an open tab of the remote instance.
 
@@ -478,4 +525,4 @@ `options` is an object with the following properties:
 
-`callback` is executed when the response to the close request is
-received. It gets the following arguments:
+`callback` is executed when the response to the close request is received. It
+gets the following arguments:
 
@@ -502,3 +549,3 @@ - `err`: a `Error` object indicating the success status;
 
-Request version information from the remote Chrome instance.
+Request version information from the remote instance.
 
@@ -538,3 +585,3 @@ `options` is an object with the following optional properties:
 
-Emitted when Chrome sends a notification through the WebSocket.
+Emitted when the remote instance sends any notification through the WebSocket.
 
@@ -547,3 +594,3 @@ `message` is the object received, it has the following properties:
 
-Refer to the [Remote Debugging Protocol specifications][rdp] for more information.
+Refer to the [Chrome Debugging Protocol] specification for more information.
 
@@ -566,3 +613,4 @@ For example:
 
-Emitted when Chrome sends a notification for `<method>` through the WebSocket.
+Emitted when the remote instance sends a notification for `<method>` through the
+WebSocket.
 
@@ -572,3 +620,3 @@ `params` is an object containing the payload.
 This is just a utility event which allows to easily listen for specific
-notifications (see the above event), for example:
+notifications (see [`'event'`](#event-event)), for example:
 
@@ -586,6 +634,6 @@ ```javascript
 Emitted every time that there are no more pending commands waiting for a
-response from Chrome. Note that the interaction with Chrome is asynchronous so
-the only way to serialize a sequence of commands is to use the callback provided
-by the `chrome.send` method. This event acts as a barrier and it is useful to
-avoid the callback hell in certain simple situations.
+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
+`chrome.send` method. This event acts as a barrier and it is useful to avoid the
+callback hell in certain simple situations.
 
@@ -604,7 +652,8 @@ For example to load a URL only after having enabled the notifications of both
 In this particular case, not enforcing this kind of serialization may cause that
-Chrome doesn't properly deliver the desired notifications the client.
+the remote instance does not properly deliver the desired notifications the
+client.
 
 #### chrome.send(method, [params], [callback])
 
-Issue a command to Chrome.
+Issue a command to the remote instance.
 
@@ -615,9 +664,10 @@ `method` is a string describing the command.
 
-`callback` is executed when Chrome sends a response to this command, it gets the
-following arguments:
+`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 Chrome;
-- `response`: an object containing either the response sent from Chrome
-  (`result` field, if `error === false`) or the indication of the error (`error`
-  field, if `error === true`).
+- `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`).
 
@@ -627,4 +677,4 @@ When `callback` is omitted a `Promise` object is returned instead, with the
 
-Note that the field `id` mentioned in the [Remote Debugging Protocol
-specifications][rdp] is managed internally and it's not exposed to the user.
+Note that the field `id` mentioned in the [Chrome Debugging Protocol]
+specification is managed internally and it is not exposed to the user.
 
@@ -667,3 +717,3 @@ For example:
 
-Close the connection to Chrome.
+Close the connection to the remote instance.
 
@@ -683,10 +733,8 @@ `callback` is executed when the WebSocket is successfully closed.
 
-- [Chrome Debugging Protocol][rdp]
-- [Chrome Debugging Protocol Viewer][rdp-viewer]
-- [Chrome Debugging Protocol Google group][goole-group]
-- [Showcase Chrome Debugging Protocol Clients][clients]
+- [Chrome Debugging Protocol]
+- [Chrome Debugging Protocol Viewer](https://chromedevtools.github.io/debugger-protocol-viewer/)
+- [Chrome Debugging Protocol Google group](https://groups.google.com/forum/#!forum/chrome-debugging-protocol)
+- [Showcase Chrome Debugging Protocol Clients](https://developer.chrome.com/devtools/docs/debugging-clients)
+- [Awesome chrome-devtools](https://github.com/ChromeDevTools/awesome-chrome-devtools)
 
-[rdp]: https://developer.chrome.com/devtools/docs/debugger-protocol
-[rdp-viewer]: https://chromedevtools.github.io/debugger-protocol-viewer/
-[goole-group]: https://groups.google.com/forum/#!forum/chrome-debugging-protocol
-[clients]: https://developer.chrome.com/devtools/docs/debugging-clients
+[Chrome Debugging Protocol]: https://developer.chrome.com/devtools/docs/debugger-protocol

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Debug access

Supply chain risk

Uses debug, reflection and dynamic code execution features.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

600428

increased by3.08%

Dependency count

2

decreased by-33.33%

Lines of code

13587

increased by2.84%

Number of lines in readme file

711

increased by7.24%

Number of low supply chain risk alerts

3

decreased by-25%

Dependency changes

• - Removedrepl.history@0.1.x

• - Removedrepl.history@0.1.4(transitive)