【譯】chrome-remote-interface

摘要：該支持下列事件當到的連接已建立時觸發。取得該調試協議描述符。在關閉請求收到響應后執行，他將獲得下列參數一個對象，指明成功狀態當缺省時，將返回一個對象。當缺省時，將返回一個對象，並且狀態取決于屬性。

本文翻譯自：chrome-remote-interface
原文更新時間：July 21,2017
譯者：Pandorym

Chrome 調試協議 的接口，他提供一個使用 JavaScript API 的簡單的命令和通知抽象，幫助使用 Chrome（或任何其他合適的實現）。

這個模塊是眾多 第三方協議客戶端 之一。

下列片段加載https://github.com，并轉儲每個請求：

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) => {
        console.error(err);
        client.close();
    });
}).on("error", (err) => {
    // cannot connect to the remote endpoint
    console.error(err);
});

在 維基 中尋找更多的例子，特別注意，上面的例子可以改寫成 async / await 原型。

你可能還想查看 FAQ。

npm install chrome-remote-interface

全局安裝（-g）可以使用附隨的客戶端。

這個模塊應該和每個實現了 Chrome 調試協議 的應用程序一起工作。特別是，它已經對以下實現進行了測試：

目標（target）的含義根據實現而差異，例如，每個 Chrome 標籤代表一個目標，而對於 Node.js 一個目標是當前視察的腳本。

為了使用這個模塊，Chrome 自身或其他實現的實例 需要運行在一個已知端口（默認為localhost:9222）。

啟動 Chrome 時，使用--remote-debugging-port選項，例如：

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

在 59 之後的版本，額外使用--headless選項，例如：

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

插入設備，并啟動 端口轉發， 例如：

adb forward tcp:9222 localabstract:chrome_devtools_remote

為了視察，WebView 必需 已配置調試，並且對應的進程 ID 必需是已知的。有幾種方法可以獲得它，例如：

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

最後，可以使用如下方式啟動端口轉發：

adb forward tcp:9222 localabstract:webview_devtools_remote_

安裝并運行 Edge 診斷配適器（Diagnostics Adapter）。

啟動 Node.js 使附加--inspect選項，例如：

node --inspect=9222 script.js

安裝并運行 iOS WebKit 調試代理（Debug Proxy）。

這個模塊有一個附隨的客戶端應用程序，他可用於交互式的控制遠程實例。

該附隨的客戶端提供用於與 HTTP 前端交互的子命令（例如，List、New 等）,運行--help以顯示一個可用選項的列表。

下面是一些例子：

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

使用子命令inspect可以以 REPL 方式進行 命令執行 和 事件綁定。不像常規的 API，該回調被重寫了，以方便顯示命令的返回值和事件的信息。還有，這里的事件綁定是簡化的，執行一個速寫方法（例如Page.loadEventFired()）切換事件註冊。

記住，該 REPL 接口提供了實現。

這是一個簡單的片段：

$ 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 } }
>>> Page.enable()
{ result: {} }
>>> Page.loadEventFired() // registered
{ "Page.loadEventFired": true }
>>> Page.loadEventFired() // unregistered
{ "Page.loadEventFired": false }
>>> Page.loadEventFired() // registered
{ "Page.loadEventFired": true }
>>> Page.navigate({url: "https://github.com"})
{ result: { frameId: "28677.1" } }
{ "Page.loadEventFired": { timestamp: 21385.383076 } }
>>> Runtime.evaluate({expression: "window.location.toString()"})
{ result:
   { result: { type: "string", value: "https://github.com/" },
     wasThrown: false } }

為了減少來自事件監聽器的數據顯示量，可以提供一個過濾函數。在這個例子中，只顯示資源的 URL：

$ 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" }

在 REPL和常規 API 中的每個協議對象都擁有在元信息中找到的描述符。此外，還添加了一個category字段，譯確定成員是command、event或type。

例如，學習如何調用Page.navigate：

>>> 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事件的參數：

>>> 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類型（注意，不同於命令和時間，類型使用大駝峰拼寫法）：

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

chrome-remote-interface默認使用本地版本的協議描述符。不停的更新這個文件，使用scripts/update-protocol.sh並且推送到這個倉庫。

這種行為可以改變在 connection 的remote選項為true，在這種情況，遠程實例要求自己提供協議描述符。

Chrome < 60.0.3097.0 不支持這麼做，所以當這種情況，將從源倉庫獲取協議描述符。

有三個選項可以覆蓋上述行為：

使用特定的協議描述符 connection (protocol 選項)；

用原始版本的命令和事件接口來使用前沿特性，這不會出現在 本地版本 的協議描述符；

更新scripts/update-protocol.sh的本地副本（當使用npm install獲取時不存在）。

這個模塊可以運行在 Web 上下文，但有明顯的局限性，即外部 HTTP請求（List,New 等）不能直接執行，因此為了使用它 用戶必須提供一個全局 criRequest：

function criRequest(options, callback) {}

options與在 Node.js http模塊中的寫法一樣，並且callback是一個接受兩個參數的函數：err（JavaScript Error對象，或null）和data（字符串返回值）。

只需要使用這個模塊，他就會工作：

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

使用 non-minified 版本手動運行 webpack ：

DEBUG=true npm run webpack

生成一個 JavaScript 文件，這可以使用

function (client) {}

function (err) {}

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

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

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

const CDP = require("chrome-remote-interface");
CDP.Activate({"id": "CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC"}, function (err) {
    if (!err) {
        console.log("target is activated");
    }
});

const CDP = require("chrome-remote-interface");
CDP.Close({"id": "CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC"}, function (err) {
    if (!err) {
        console.log("target is closing");
    }
});

const CDP = require("chrome-remote-interface");
CDP.Version(function (err, info) {
    if (!err) {
        console.log(info);
    }
});

function (message) {}

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

function (params) {}

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

function () {}

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

function () {}

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

client.send(".", params, callback);

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

client.on(".", callback);

client.Network.requestWillBeSent(console.log);

client.send("Domain.method", ...);

CDP({remote: true});

$ chrome-remote-interface inspect --remote