RemoteDebug iOS WebKit Adapter

To install the adapter globally via npm, run the following command:

npm install remotedebug-ios-webkit-adapter -g

Note: This project is no longer proactively maintained. It has been superseded by Inspect.dev.

The adapter requires ios-webkit-debug-proxy and libimobiledevice to communicate with iOS devices. You must also have the latest version of iTunes installed.

Linux

Follow the installation instructions for ios-webkit-debug-proxy and libimobiledevice.

Windows

You can use scoop to install the required dependencies:

scoop bucket add extras
scoop install ios-webkit-debug-proxy

OSX/Mac

Use Homebrew to install the --HEAD versions of the required tools:

brew update
brew unlink libimobiledevice ios-webkit-debug-proxy usbmuxd
brew uninstall --force libimobiledevice ios-webkit-debug-proxy usbmuxd
brew install --HEAD usbmuxd
brew install --HEAD libimobiledevice
brew install --HEAD ios-webkit-debug-proxy

To allow the adapter to detect your iOS targets, you must enable the Web Inspector on the device:

1. Open iOS Settings.
2. Navigate to Safari preferences.
3. Enable Web Inspector.

Additionally, ensure your computer trusts the iOS device. On macOS, you can use Safari to inspect an iOS Safari tab to establish trust. On Windows, iTunes may prompt you with a "Trust this computer" dialog.

To view debug logs for the adapter, set the DEBUG environment variable to remotedebug when starting the application.

DEBUG=remotedebug npm start

To use Mozilla debugger.html, start the adapter on port 9222 and select the Chrome tab within the tool:

remotedebug_ios_webkit_adapter --port=9222

To use Visual Studio Code, install the VS Code Chrome Debugger extension. Create a launch.json configuration file and set the port to match your adapter's port (default 9000).

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "iOS Web",
            "type": "chrome",
            "request": "attach",
            "port": 9000,
            "url": "http://localhost:8080/*",
            "webRoot": "${workspaceRoot}/src"
        }
    ]
}

When initializing or configuring the adapter, you can provide an IAdapterOptions object to control its behavior. Key options include:

• pollingInterval: Frequency of polling (number).
• baseUrl: The base URL for the adapter.
• path: The specific path for the adapter.
• port: The port number the adapter should run on.
• proxyExePath: Path to a proxy executable.
• proxyExeArgs: An array of arguments to pass to the proxy executable.

When initializing an Adapter, you can provide an IAdapterOptions object. The following configuration keys are used to define how the adapter connects to the underlying debugging endpoint:

• pollingInterval: The interval (in milliseconds) for polling targets. Defaults to 3000.
• baseUrl: The base URL for the debugging endpoint. Defaults to http://127.0.0.1.
• path: The path for the JSON endpoint. Defaults to /json.
• port: The port for the debugging endpoint. Defaults to 9222.
• proxyExePath: The path to the proxy executable required to start the adapter process.
• proxyExeArgs: Arguments to pass to the proxy executable.

The IOSAdapter uses IIOSProxySettings to manage the connection via ios_webkit_debug_proxy. When calling getProxySettings(args), the adapter automatically constructs arguments for the proxy executable.

If you are providing arguments via the args object, ensure proxyPort is specified. The adapter will generate a --config string in the format: --config=null:<proxyPort>,:<port_range> where the port range is a block of 100 ports starting from proxyPort + 1.

Proxy Requirements:

• Windows: The adapter looks for ios_webkit_debug_proxy.exe in Scoop directories (%SCOOP%/apps/ios-webkit-debug-proxy/current/ or %USERPROFILE%/scoop/apps/ios-webkit-debug-proxy/current/).
• macOS/Linux: The ios_webkit_debug_proxy executable must be available in your system PATH.

The following options are available for the remotedebug_ios_webkit_adapter command line tool:

Usage: remotedebug_ios_webkit_adapter --port [num]

Options:
  -p, --port  the adapter listening port  [default: 9000]
  --version   prints current version

If the adapter fails to locate the proxy executable, check the following based on your operating system:

• Windows: Ensure you have installed the proxy via Scoop. The adapter expects it at: path.resolve(__dirname, process.env.SCOOP + '/apps/ios-webkit-debug-proxy/current/ios_webkit_debug_proxy.exe').
  • Command to fix: scoop install ios-webkit-debug-proxy
• macOS/Linux: Ensure ios_webkit_debug_proxy is in your system PATH.
  • Command to fix: Install via your package manager or from https://github.com/google/ios-webkit-debug-proxy.

If you encounter device version detection errors, the adapter suggests updating ios-webkit-debug-proxy to version 1.8.5 or higher.