Remotely debugging iOS Safari on Windows and Linux

Note: This blog post is a mirror of the README of my GitHub repository.

Using this project you can debug your websites and web applications running in iOS Safari from a PC running Windows or Linux.

It provides a free and up-to-date alternative to the discontinued remotedebug-ios-webkit-adapter by RemoteDebug and is the spiritual successor to the abandoned webkit-webinspector by Arty Gus.

The setup scripts (generate.sh or generate.ps1) download the latest version of WebKit’s built-in WebInspector and patch it to work with the WebSocket ios-webkit-debug-proxy provides and to be compatible with Chromium based browsers.

Requirements for running

ios-webkit-debug-proxy
- On Windows, it will automatically be downloaded, but you must also install iTunes for it to work
- For Linux, please follow the installation instructions.
Node.JS http-server or Python or PHP
- If you have Python or PHP on your system, you don’t need to change anything
- If you have Node.JS on your system, just run npm i -g http-server and you’re set.
A Chromium based browser
- like Google Chrome, Edge or Opera
or WebKit based browser
- like Epiphany/GNOME Web

Requirements for setup

svn (for generate.sh) or git (for generate.ps1) for downloading WebKit source code
- On Windows, I suggest using git for Windows in PowerShell
- On Linux, I suggest installing svn from your package manager

Instructions

Setup

Clone this repository, https://github.com/HimbeersaftLP/ios-safari-remote-debug-kit to your PC
On Windows, run generate.ps1. On Linux, run generate.sh.

This will result in the folder WebKit being created inside src. It contains the WebInspector files.

Running

Plug your iOS device into your PC via USB
On the iOS device, go to Settings->Safari->Advanced->Web Inspector and enable it
Open the website you want to debug in Safari
On Windows, run start.ps1. On Linux, run start.sh.
Then open the Chromium or WebKit based browser of your choice with the following URL: http://localhost:8080/Main.html?ws=localhost:9222/devtools/page/1
You should be greeted with the WebInspector and can now debug to your heart’s content.

Exiting

Windows

Two windows will open. One manages the web server and the other one is ios-webkit-debug-proxy.
To exit, close the ios-webkit-debug-proxy window, the other one will close automatically
- Alternatively you can also press Ctrl+C in the web server window

Linux

Press Ctrl+C in the terminal window to exit

Known Issues

"Events" on the "Timelines" tab don’t work
Canvas content doesn’t show on the "Graphics" tab
Minor style glitches due to Webkit vs. Chromium differences

Notes

If you want to see details about how this was made, you can read a detailed explanation in in my other post here.

Attribution

This project was made possible thanks to
- webkit-webinspector for the idea
- ios-webkit-debug-proxy for the ios-webkit-debug-proxy tool
- WebKit for the WebInspector itself

Categories: CodingUseful

Tags: debuggingdevtoolsiosremote debuggingsafariwebkit

13 Comments

Nicholas Fenwick · 26th June 2023 at 09:44

Hi! When trying to debug an old iPhone running iOS (and therefore Safari) 12, do we need to issue commands to change the webkit protocol to 12? I can list available pages with http://localhost:9222/ but when I try to run http://localhost:8000/Main.html?ws=localhost:9222/devtools/page/1 the Web Inspector throws an error “‘Browser’ domain was not found (at :undefined:undefined)”. This message is mentioned at https://github.com/HimbeersaftLP/ios-safari-remote-debug-kit but I am not “trying to inspect a page that is not inspectable” since this same page on a newer iPhone 16 and same URL works fine.

Himbeer · 26th June 2023 at 10:51

Hello,
You can select the iOS version when running generate.sh/generate.ps1 using “-i ” or “-iOSVersion ” respectively. (You also need to run with “-f” or “-Force” if you already ran the script before to clean up the old data)
Using an incompatible iOS version usually results in an “Unknown Instrument” error (https://github.com/HimbeersaftLP/ios-safari-remote-debug-kit/issues/12).
Does the list at http://localhost:9222/ only show this one page? The message “Error: ‘Browser’ domain was not found” usually indicates a successfull WebSocket connection but the selected page/Safari not cooperating with the debugger.

Alex Malz · 9th February 2023 at 15:06

Thank you very much for your great project! Works very well for me and is so easy to install and use!! I previously wasted hours with compiling the old webkit stuff without any benefit…

However, do you have any idea how to get it working with vs code? As vs code is capable of the chrome remote debug protocol it should work somehow. I just don’t get the correct settings for the launch.json configuration.

Thanks! Alex.

Himbeer · 9th February 2023 at 15:13

Hi Alex!
You are right that VS Code is capable of the Chrome Remote Debug protocol. However, WebKit uses their own protocol, that’s why my tool bundles the WebKit inspector.
There used to be a tool that could translate between the protocols (remotedebug-ios-webkit-adaptor) and also a VS Code extension with the same purpose (vscode-ios-web-debug), however those are sadly both deprecated (which is the reason I made this project, as running the WebKit inspector is far less maintenance effort than keeping up to date with the inspector protocol).

Alex · 9th February 2023 at 16:31

Thanks for your reply and – again – your great work!

Himbeer · 9th February 2023 at 16:33

You’re welcome!

EVC · 26th July 2022 at 15:09

I just get

“This site can’t be reached

localhost refused to connect.

ERR_CONNECTION_REFUSED”

Any ideas?

Himbeer · 10th August 2022 at 23:14

Edit the powershell script to use another web server

Rodrigo · 16th February 2022 at 13:13

Hi!

Thanks for the repo and the blog. I have managed to install most of it but the web server is not loading in Chrome. I get localhost refused to connect.

I tried going directly to http://localhost:9222/ and there it shows my ipad and the web I want to debug that is open but when going to http://localhost:9222/devtools/page/1 it says:

404. That’s an error.

The requested URL /devtools/page/1 was not found. Frontend is disabled

It is using Python3 to serve the WebInspector

Himbeer · 19th February 2022 at 10:57

Hello! Using the python (or other) webserver instead of the page served by the ios-webkit-debug-proxy is necessary as the latter is very outdated. It looks like there might be something else already using port 8080 on your machine that causes the webserver of my script not to load. Try changing the port number in the script.

Joe · 21st June 2021 at 20:50

Hi, I just wanted to write and say THANK YOU VERY MUCH for making these scripts available, and also for taking the time to document everything. I had been pulling my hair out trying to just simply get proper error messages from iOS Safari console. Apple is totally unreasonable with their restricted access to the crippled web browser on iOS, and they furthermore prevent you from really having any other alternatives either because every browser is on iOS is still running the webKit engine as a rule. People like you, however, are making a difference, and I just wanted to say thanks for the effort. If there is a place to make a donation to you, I’d be willing to do so because you have saved me hundreds of dollars by circumventing the necessity to buy an actual Mac just to test my software against their awfully crippled browser, Safari. Your efforts are much appreciated. Thanks, Joe.

Himbeer · 8th July 2021 at 12:03

Thank you for your cheerful comment! I am very glad my project turned out useful for you. I appreciate your offer, but I think there are places that need a donation more than me ^^. btw I love the animations on your website 😀

Joe Harris · 8th July 2021 at 18:31

Thank you once again! 🙂

Remotely debugging iOS Safari on Windows and Linux

Published by Himbeer on 3rd June 20213rd June 2021

Requirements for running

Requirements for setup