Awesome
Remote Debugging iOS Safari on Windows and Linux
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. It is a free and open source alternative to inspect.dev.
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.
If you are looking for a more modern, self-contained tool built in Go, check out Hazel's ios-safari-remote-debug.
Requirements for running
ios-webkit-debug-proxy
- On Windows, it will automatically be downloaded, but you must also install and trust the device in 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
git
(required bygenerate.sh
orgenerate.ps1
) for downloading WebKit source code- On Windows, I suggest using
git
for Windows in PowerShell - On Linux, I suggest installing
git
from your package manager
- On Windows, I suggest using
Instructions
Setup
- Clone this repository to your PC
- On Windows, run
generate.ps1
. On Linux, rungenerate.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 Windows, open iTunes and mark the iOS device as trusted (pop-up asks for confirmation the first time you connect a new device)
- On the iOS device, confirm that you trust the connection if asked
- 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, runstart.sh
. Make sure your iOS device's screen is unlocked. - The
ios-webkit-debug-proxy
will show your iOS device's name as connected. - 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
- If you have mutliple pages open or extensions installed, refer to http://localhost:9222/ for the page number that is at the end of the URL
- You should be greeted with the WebInspector and can now debug to your heart's content.
Troubleshooting
- If you get an error like
Uncaught (in promise) Error: 'Browser' domain was not found
fromConnection.js:162
you are trying to inspect a page that is not inspectable (this could be caused by having Safari extensions installed). Refer to http://localhost:9222/ for the available pages and put the correct one at the end of the URL (for examplehttp://localhost:8080/Main.html?ws=localhost:9222/devtools/page/2
) for inspecting the second page. - In case your inspector window stays empty, open the dev tools of your local browser to check the console for errors.
- If you get an error like
WebSocket connection to 'ws://localhost:9222/devtools/page/1' failed:
fromInspectorFrontendHostStub.js:68
, try unplugging your device and plugging it back in while the site you want to debug is open in Safari. Once you see the ios-webkit-debug-proxy console window display a message likeConnected :9222 to Himbeers iPad (...)
, refresh the inspector page inside your browser (do not use the refresh button on the inspector page, refresh the entire site from your browser).
- If you get an error like
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 HOW_IT_WORKS.md
(note that this document only describes how the very first version of this tool was created and might not be completely up-to-date).
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