(Wireless) Remote Debugging with Safari on iOS

2018-02-10 (updated 2018-11-29) · Safari, iOS

Testing websites on mobile devices is getting more and more important. Especially given that mobile browsers often behave differently on physical devices than you might expect them to when just testing on a desktop browser with a smaller viewport. So it is important to constantly test your development websites on real devices.

Most development servers on a desktop computer just open a certain port on the localhost so that the content they serve is accessible on a URL like http://localhost:1234 . That works well on the computer but you cannot just paste that URL into your mobile device and start testing. A working (most of the time (It actually depends on the server whether or not it allows remote connections using the computer's IP address. See below on how to fix that.)) but naive solution is to look up the current IP address of the computer and open http://<ip-address-of-desktop>:<port> on the mobile device.

But relying on the computer's IP address is annoying as it might change from time to time. And that means that you can't bookmark it on your mobile device, you loose cookies, local storage, site settings, etc. on every IP address change. There is, however, a simple one-time setup that does not involve using variable IP addresses or external tools. And it even works without a cable connection. All you need is a Mac and Safari. This solution works with macOS 10.12 (Sierra), 10.13 (High Sierra), 10.14 (Mojave), and probably older versions too.

Open localhost:<port> on your Mobile Device

Let's assume your test server opens the port 8080 on the localhost. On your computer, you will thus use http://localhost:8080 to access the development website. Now lets enable that on your iOS device. Actually, we don't open localhost:<port> or <ip-address>:<port> on the mobile as there is an even better way. Instead of using the IP address directly, we will use the computer name of your Mac. You can get that, for example, by opening System Preferences → Sharing. In my case, the name is “STMP”. Note that I will refer to your computer's name by using <computer-name> for the rest of this article. Now that you know the name, make sure that you activate at least one item in the list of sharing services. It does not matter what sharing service you activate, but you have to enable at least one. This might be something silly, for example activate Printer Sharing and only allow it to be used by yourself.

Now make sure that both your Mac and iOS device are connected to the same WiFi network. Open http://<computer-name>.local:8080 (or whichever port you use on your computer) on your mobile device. Note that you have to replace whitespaces with dashes and ignore special characters such as ' . For example, if your computer name is Name's MacBook , you will have to use http://Names-MacBook.local . And tada, your website should show up on your iPhone or iPad!

That does not work (For example, you get the error message “Safari cannot open the page because it could not connect to the server”?) for you? Then it looks like you have to configure your server to bind to 0.0.0.0 instead of localhost (and to allow connections from *.local hosts). Changing the IP address to 0.0.0.0 will make your server externally accessible (within the same WiFi).

For example if you are using webpack-dev-server with Node.js, you have to slightly tweak its configuration. By default, it creates a server on localhost and will not allow remote connections (e.g. from mobile devices). So you need to change the webpack DevServer configuration (more specifically, host and allowedHosts ) accordingly:

devServer: { host: '0.0.0.0', allowedHosts: [ '.local', ], },

Note that adding .local to allowedHosts will enable any hosts ending with .local . That makes it a good choice on shared code bases. Restart the server and it should work after all, yay! But if you you get the error message invalid host header , there is probably a mismatch between your computer's name and the URL that you enter in the address bar of your browser.

Note that actually all iPhones, iPads, and Macs in the same WiFi network now have access to your local development website. And that not only works for mobile Safari, but also with the iOS versions of Firefox and Chrome. However, you cannot use remote debugging on those (see next section on how to do that with Safari). As they use the same rendering engine as mobile Safari, though, it should not be needed anyway.

Remote Debugging

Now that you have access to your websites from your phone and tablet, you probably also would like to use remote debugging with them. Setting that up is actually very simple. Open the Safari Preferences → Advanced and enable “Show Develop menu in menu bar".

On your mobile, enable Settings → Safari → Advanced → Web Inspector and then connect it to your computer with a cable. Make sure that you open Safari on mobile and on the Mac. On the Mac Safari select Develop → <Your mobile Device Name> from the menu. When you set this up for the first time on that device, you need to click Use for Development… and tap Trust on the mobile device.

Now everything is set up for remote debugging. Just select Develop → <Your mobile Device Name> → <Tab you want to debug> on the Mac Safari and a new debugging session will be created. That allows you to inspect the website on your iPhone or iPad from the Mac Safari.

Remote Debugging without a Cable

Remote debugging with mobile Safari also works without a cable connection to the desktop computer. But you have to install Safari Technology Preview on your Mac as the stable Safari version currently does not support wireless remote debugging (This might be outdated. Check whether the normal Safari already supports this or not. If it does, there is no need to install Safari Technology Preview anymore.). Just do the same setup as described above, but connect the cable and open Safari on your iOS device. In Safari Technology Preview, make sure you enabled “Show Develop menu in menu bar” and enable Develop → <Your mobile Device Name> → Connect via Network in the menu. Now you can unplug the cable and check whether Develop → <Your mobile Device Name> still shows up on the desktop Safari.

Then just select the tab you want to remote debug from the same menu. Safari Technology Preview will establish a wireless connection from macOS to the iOS device which allows you to inspect your local websites from iPhones and iPads. See, no cable.

Happy Testing!