chrome-remote-interface

Choosing between chrome-remote-interface and Puppeteer depends on your requirements:

• Puppeteer: A high-level API built on top of the Chrome Debugging Protocol. It often uses a bundled version of Chromium. Use Puppeteer if you want a higher-level abstraction for common tasks.
• chrome-remote-interface: A general-purpose 1:1 Node.js binding for the Chrome Debugging Protocol. Use this if you need full access to the raw protocol to implement your own high-level APIs or custom logic.

When running this module in a web browser, external HTTP requests (such as those used by list or new) cannot be performed directly. You must provide a global criRequest function to handle these requests.

The criRequest function must follow this signature:

• options: An object identical to the one used by the Node.js http module.
• callback: A function receiving two arguments: err (a JavaScript Error object or null) and data (the string result).

The module works with any application implementing the Chrome Debugging Protocol:

• Opera: opera --remote-debugging-port=9222
• Node.js: node --inspect=9222 script.js (requires v6.3.0+)
• Edge: MicrosoftEdge.exe --devtools-server-port 9222 about:blank
• Firefox (Nightly): firefox --remote-debugging-port 9222 (experimental feature)

To use the interface, you must start Chrome with the --remote-debugging-port option.

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

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

Android:

1. Connect the device and authorize the connection.
2. Enable port forwarding via ADB:

adb -d forward tcp:9222 localabstract:chrome_devtools_remote Note: Android uses a local version of the protocol.

WebView:

1. Configure the WebView for debugging.
2. Find the PID:

adb shell grep -a webview_devtools_remote /proc/net/unix 3. Enable port forwarding: adb forward tcp:9222 localabstract:webview_devtools_remote_<pid>

To generate a standalone JavaScript file for use with a <script> element in a browser environment, follow these steps:

1. Install dependencies: npm install from the root directory.
2. Run webpack with the TARGET=var environment variable: TARGET=var npm run webpack.
3. Include the generated file in your HTML after defining the required criRequest function.

npm install
TARGET=var npm run webpack

<script>
  function criRequest(options, callback) { /* implementation */ }
</script>
<script src="chrome-remote-interface.js"></script>

TypeScript definitions are available via DefinitelyTyped. Install them using:

npm install --save-dev @types/chrome-remote-interface

Note on versioning: The definitions are automatically generated from devtools-protocol@0.0.927104. If you need to use a different version of devtools-protocol, you must manually patch the node_modules/devtools-protocol/types folder with the contents from the corresponding ChromeDevTools/devtools-protocol repository and use patch-package to persist the changes.

By default, chrome-remote-interface asks the remote instance to provide its own protocol. You can override this behavior using the following methods:

1. Use the local protocol descriptor: Set the local option to true during connection. This uses the protocol descriptor bundled with the library (lib/protocol.json).
2. Pass a custom protocol descriptor: Provide a custom descriptor via the protocol option during connection.
3. Use raw interfaces: Use the raw version of the send method and events interface to access bleeding-edge features not yet present in the local protocol descriptor.

If you encounter the error Domain.method wasn't found, the custom or local protocol descriptor you provided via CDP({protocol: customProtocol}) declares a method that the currently running Chrome version does not support.

To inspect the protocol descriptor currently available to your environment, use the following command:

$ chrome-remote-interface inspect

If you encounter the error Domain.methodOrEvent is not a function, the method or event you are attempting to use is missing from your current protocol descriptor.

• If fetching protocol from Chrome: Your version of Chrome does not support this feature. Update Chrome.
• If using a custom protocol: Your protocol version is obsolete. Provide an up-to-date descriptor.
• If using the embedded protocol: Ensure you are running the latest version of chrome-remote-interface.

If your program stalls or behaves unexpectedly when running Chrome in a Docker container, it is likely because the default /dev/shm size (64MB) is insufficient for Chrome to navigate certain web pages.

To resolve this, increase the shared memory size when running your container using the --shm-size flag.

--shm-size=256m