iOS WebKit Debug Proxy guide

Overview

WebKit Debug Proxy is a tool for debugging web content on iOS devices. This guide will help you set up and use WebKit Debug Proxy for iOS device debugging.

Tip: this is the command-line route and it needs macOS. If you just want to debug iOS pages from Windows, macOS or Linux without configuring a proxy, use iOS Safari debugging instead.

Installation

1. Install dependencies

# Install Homebrew (if you do not have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install WebKit Debug Proxy
brew install ios-webkit-debug-proxy

2. Configure the device

Enable Web Inspector on the iOS device:
- Open Settings > Safari > Advanced
- Enable Web Inspector
Connect the device:
- Connect the iOS device to the Mac with a USB cable
- Trust the computer on the device

Usage

1. Start the proxy

ios_webkit_debug_proxy

2. Connect the device

Open Safari
Open Safari’s Develop menu on the Mac
Select the iOS device you want to debug
Select the page you want to debug

3. Debugging features

Element inspection
JavaScript debugging
Network analysis
Performance analysis

Advanced usage

Multi-device debugging

ios_webkit_debug_proxy -c [device-id]:[port]

Custom port

ios_webkit_debug_proxy -p [port]

Save the debugging session

ios_webkit_debug_proxy -d [output-directory]

Troubleshooting

Common problems

Device not found
- Check the USB connection
- Confirm the device has trusted the computer
- Restart the device and the proxy
Connection fails
- Check whether the port is already in use
- Confirm Web Inspector is enabled
- Try restarting the proxy
Unstable debugging
- Check the network connection
- Update WebKit Debug Proxy
- Restart the device and the computer

Best practices

Use the latest version of WebKit Debug Proxy
Keep the iOS / macOS versions on the device and computer up to date
Clear out old debugging session records regularly
Use workspaces to manage multiple debugging projects