iOS WebKit Debug Proxy

Go back to tutorial

The ios_webkit_debug_proxy (aka iwdp) proxies requests from usbmuxd daemon over a websocket connection, allowing developers to send commands to MobileSafari and UIWebViews on real and simulated iOS devices. For accessing web views on real iOS device appium uses ios_webkit_debug_proxy.

Design

Installation

iOS WebKit Debug Proxy works on Linux, MacOS & Windows.

On a MacOS, it’s easiest to install with homebrew:

brew install ios-webkit-debug-proxy

On Windows, it’s easiest to install with scoop:

scoop bucket add extras

scoop install ios-webkit-debug-proxy

On Linux:

sudo apt-get install autoconf automake libusb-dev libusb-1.0-0-dev libplist-dev libplist++-dev usbmuxd libtool libimobiledevice-dev

git clone https://github.com/google/ios-webkit-debug-proxy.git

cd ios-webkit-debug-proxy

./autogen.sh

make

sudo make install

Building ios-webkit-debug-proxy from source:

Open the command terminal on your mac. You can find instructions on how to open the terminal via your favorite search engine. Once that is open, verify you have Homebew installed:

$ brew -v

When you’re certain you have Homebrew, do the following (the $ indicates the command line prompt, do not enter it):

$ cd  ~

$ sudo apt-get install autoconf automake libusb-dev libusb-1.0-0-dev libplist-dev libplist++-dev usbmuxd libtool libimobiledevice-dev

$ git clone https://github.com/google/ios-webkit-debug-proxy.git

$ cd ios-webkit-debug-proxy

$ ./autogen.sh

$ make

$ sudo make install

Usage

On Linux, you must run the usbmuxd daemon. The above install adds a /lib/udev rule to start the daemon whenever a device is attached.

To verify that usbmuxd can list your attached device(s), ensure that libimobiledevice-utils is installed, or install it with:

sudo apt-get install libimobiledevice-utils

and then run idevice_id -l

Start the simulator or device – The iOS Simulator is supported, but it must be started before the proxy. The simulator can be started in XCode, standalone, or via the command line:

# Xcode changes these paths frequently, so doublecheck them

SDK_DIR=”/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs”

SIM_APP=”/Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/Contents/MacOS/Simulator”

$SIM_APP -SimulateApplication $SDK_DIR/iPhoneSimulator8.4.sdk/Applications/MobileSafari.app/MobileSafari

Enable the inspector – Your attached iOS devices must have ≥1 open browser tabs and the inspector enabled via: Settings > Safari > Advanced > Web Inspector = ON

Start the proxy

ios_webkit_debug_proxy

• –debug for verbose output.
• –frontend to specify a frontend
• –help for more options.
• Ctrl-C to quit. Also, the proxy can be left running as a background process.

Using with DevTools – ios_webkit_debug_proxy can be used with many tools such as Chrome DevTools and Safari Web Inspector.

Chrome Devtools – To use Chrome DevTools it’s the recommendation to use the RemoteDebug/remotedebug-ios-webkit-adapter project, which has instructions on how to setup Chrome to remote debug iOS devices, much similar to Android debugging.

The reason is that recent versions of Chrome and Safari there’re major discrepancies between Chrome Remote Debugging Protocol and Apple’s Remote Web Inspector service, which means that newer versions of Chrome DevTools aren’t compatible with Safari.

Safari Web Inspector – You can use Safari Web Inspector extracted from Webkit sources, e.g. artygus/webkit-webinspector.

Firefox DevTools via Valence – Another option is mozilla/valence which enables Firefox DevTools to be used with iOS.

Configuration

View and inspect debuggable tabs –  Navigate to localhost:9221. You’ll see a listing of all connected devices. Click through to view tabs available on each, and click through again to open the DevTools for a tab.

Setting the DevTools UI URL – Chrome DevTools UI used as a default frontend:

http://chrome-devtools-frontend.appspot.com/static/27.0.1453.93/devtools.html

You can use the -f argument to specify different frontend source, like Chrome’s local DevTools, a local Chromium checkout or another URL:

# examples:

ios_webkit_debug_proxy -f chrome-devtools://devtools/bundled/inspector.html

ios_webkit_debug_proxy -f ~/chromium/src/third_party/WebKit/Source/devtools/front_end/inspector.html

ios_webkit_debug_proxy -f http://foo.com:1234/bar/inspector.html

If you use -f chrome-devtools://devtools/bundled/inspector.html, you won’t be able to click the links shown in localhost:9222 as Chrome blocks clicking these URLs. However, you can copy/paste them into the address bar.

Just the same, you can apply the appropriate port (9222) and page (2) values below.

chrome-devtools://devtools/bundled/inspector.html?ws=localhost:9222/devtools/page/1

The -f value must end in “.html”. Due to security reasons, https URLs will not work; use http or force-allow with the URL bar’s shield icon. As of Chrome 45, the primary URL changed from devtools.html to inspector.html.

To disable the frontend proxy, use the –no-frontend argument.

Port assignment – The default configuration works well for most developers. The device_id-to-port assignment defaults to:

:9221 for the device list

:9222 for the first iOS device that is attached

:9223 for the second iOS device that is attached

…

:9322 for the max device

If a port is in use then the next available port will be used, up to the range limit.

The port assignment is first-come-first-serve but is preserved if a device is detached and reattached, assuming that the proxy is not restarted, e.g.:

• start the proxy
• the device list gets :9221
• attach A gets :9222
• attach B gets :9223
• detach A, doesn’t affect B’s port
• attach C gets :9224 (not :9222)
• reattach A gets :9222 again (not :9225)

The port assignment rules can be set via the command line with -c. The default is equivalent to:

ios_webkit_debug_proxy -c null:9221,:9222-9322

where “null” represents the device list. The following example restricts the proxy to a single device and port:

ios_webkit_debug_proxy -c 4ea8dd11e8c4fbc1a2deadbeefa0fd3bbbb268c7:9227

Running ios-webkit-debug-proxy

Once installed you can start the proxy with the following command:

# Change the udid to be the udid of the attached device and make sure to set the port to 27753

# as that is the port the remote-debugger uses. You can learn how to retrieve the UDID from

# Apple’s developer resources.

> ios_webkit_debug_proxy -c 0e4b2f612b65e98c1d07d22ee08678130d345429:27753 -d

You can also set the desired capability called startIWDP to true. This will run the above command as a subprocess from within Appium and will set the udid, so you don’t have to run ios_webkit_debug_proxy yourself anymore. It monitors the proxy for crashes and relaunches when needed.

// example desired capabilities

{

“browserName”: “Safari”,

“platformName”: “iOS”,

“deviceName”: “iPhone 7”,

“automationName”: “XCUITest”,

“startIWDP”: true,

“udid”: “auto”

}

You may also use ios-webkit-debug-proxy-launcher, a small script included with the Appium codebase, to launch the proxy. It monitors the proxy log for errors, and relaunch the proxy where needed. This is also optional and may help with recent devices:

# change the udid

# note, this is run from an Appium repository

> ./bin/ios-webkit-debug-proxy-launcher.js -c 0e4b2f612b65e98c1d07d22ee08678130d345429:27753 -d

The proxy requires the “web inspector” to be turned on to allow a connection to be established. Turn it on by going to settings > safari > advanced.

Specifying non-default port – Appium expects ios-webkit-debug-proxy to be running on port 27753. If, for whatever reason, this needs to be changed, the webkitDebugProxyPort desired capability can be set with the port on which it the proxy is running.

Go back to tutorial