Remote debugging with weinre

Warning This article was written over six months ago, and may contain outdated information.

Remote debugging of sites on mobile and tablets is getting a little easier, but still has too many pain points; for example, while you can debug iOS Safari through desktop Safari, you can only do so with a single device at a time; and to debug on Android you have to download and install the full SDK, and even that only works with Chrome.

Adobe Edge Inspect is useful for remote debugging but is limited by many requirements: you must install an app on each target device, so it won’t work on any platform other than Android or iOS; it uses Chrome desktop for the debug tools (although a new open API may open that to other browsers); and you must buy a subscription to unlock multi-device debugging.

If you want to do truly cross-platform remote debugging on the cheap you need weinre, a free and open source project which is actually the basis of Edge Inspect; Adobe bought the technology, then released the original source under an open license. weinre’s quite easy to install, although it doesn’t appear to be, so in this article I’m going to lay out the few simple steps required to get it up and running.

There are a few prerequisites: you’ll need a local development server (I’m using Apache) and to have installed Node.js. Note that I use Ubuntu for my development at home, but these instructions will work equally well on OSX. Sorry, Windows users, I can’t currently test on your platform so can’t swear this will work for you.

Installation and setup

The first step is to install weinre. In the past this ran on a horrible Java server, but recent development work means it now runs in Node and is therefore much more simple to install, using NPM. To install it globally, use this terminal command:

sudo npm install -g weinre

When it’s finished installing, run it with the weinre command. By default weinre will only run on localhost, so I’m also adding the value –all– to the –boundHost option to make it run on all IP addresses, making it available to external devices:

weinre --boundHost -all-

If you want to check that it’s running correctly, go to http://localhost:8080/ in Chrome, Firefox, IE10 or Safari; you should see some on-screen instructions which will confirm that it’s operating.

Begin debugging

The next step is to make the pages you want to test visible to all devices. To achieve this you’ll need your IP address. If you don’t now how to find this, type ifconfig into the terminal and look for the inet number; for this tutorial, let’s presume it’s 123.456.7.89.

When you have this, you must include the following script (with your own IP, obviously) in the head of every page you want to test:

<script src="http://123.456.7.89:8080/target/target-script-min.js#anonymous"></script>

To start debugging, visit any page which includes this script; you can use localhost if you’re on the same machine as your server, or use the IP address on external devices. For example, if you’re testing hello.html, go to http://localhost/hello.html from the machine running the server, and http://123.456.7.89/hello.html from any external devices you want to debug.

On the machine running the server, open the debugging client by going to the URL http://localhost:8080/client/#anonymous. In the section called Targets you’ll see a list of devices that are currently visiting your test page. If there are multiple devices, choose the one you want to debug — it will be highlighted in green. You can now begin to debug your page using the built-in tools, which are based on the WebKit inspector (regardless of the browser you’re using).

Next steps

Once you’ve got weinre up and running I suggest you read through the full documentation to get the most out of it — especially regarding setting up a server properties file for making weinre easier to run, or to get the bookmarklet which removes the need for including the script in your document head.

And if you’re doing substantial multi-device testing you may want to look at a way of keeping all of the devices in sync, with an app like Shim (note: I haven’t done this myself yet, no idea if it works).

Most importantly, make sure you get a deep understanding of how the web inspector tools work to really get the most from your debugging.

5 comments on
“Remote debugging with weinre”

  1. You saved my night! thanks :)

  2. Since Weinre attaches itself to the target HTML document via JavaScript, it is unable to catch events and errors that happen before it is loaded. Thus, the Network and Timeline pages are not much of use, and the Resources page only shows limited data.

  3. @Ropo: Sure, and most modern tools are better; But if you want to debug older Android, for example, it’s still a good option.

  4. Very helpful, thanks

  5. Thanks, that’s great for debugging Android stock browser.