Remote debugging with weinre

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

Remote debug­ging of sites on mobile and tablets is get­ting a lit­tle eas­i­er, but still has too many pain points; for exam­ple, while you can debug iOS Safari through desk­top Safari, you can only do so with a sin­gle device at a time; and to debug on Android you have to down­load and install the full SDK, and even that only works with Chrome.

Adobe Edge Inspect is use­ful for remote debug­ging but is lim­it­ed by many require­ments: you must install an app on each tar­get device, so it won’t work on any plat­form oth­er than Android or iOS; it uses Chrome desk­top for the debug tools (although a new open API may open that to oth­er browsers); and you must buy a sub­scrip­tion to unlock mul­ti-device debugging.

If you want to do tru­ly cross-plat­form remote debug­ging on the cheap you need weinre, a free and open source project which is actu­al­ly the basis of Edge Inspect; Adobe bought the tech­nol­o­gy, then released the orig­i­nal source under an open license. wein­re’s quite easy to install, although it does­n’t appear to be, so in this arti­cle I’m going to lay out the few sim­ple steps required to get it up and running.

There are a few pre­req­ui­sites: you’ll need a local devel­op­ment serv­er (I’m using Apache) and to have installed Node.js. Note that I use Ubun­tu for my devel­op­ment at home, but these instruc­tions will work equal­ly well on OSX. Sor­ry, Win­dows users, I can’t cur­rent­ly test on your plat­form 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 hor­ri­ble Java serv­er, but recent devel­op­ment work means it now runs in Node and is there­fore much more sim­ple to install, using NPM. To install it glob­al­ly, use this ter­mi­nal command:

sudo npm install -g weinre

When it’s fin­ished installing, run it with the weinre com­mand. By default weinre will only run on local­host, so I’m also adding the val­ue -all- to the --boundHost option to make it run on all IP address­es, mak­ing it avail­able to exter­nal devices:

weinre --boundHost -all-

If you want to check that it’s run­ning cor­rect­ly, go to http://localhost:8080/ in Chrome, Fire­fox, IE10 or Safari; you should see some on-screen instruc­tions which will con­firm that it’s operating.

Begin debugging

The next step is to make the pages you want to test vis­i­ble to all devices. To achieve this you’ll need your IP address. If you don’t now how to find this, type ifcon­fig into the ter­mi­nal and look for the inet num­ber; for this tuto­r­i­al, let’s pre­sume it’s 123.456.7.89.

When you have this, you must include the fol­low­ing script (with your own IP, obvi­ous­ly) 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 debug­ging, vis­it any page which includes this script; you can use local­host if you’re on the same machine as your serv­er, or use the IP address on exter­nal devices. For exam­ple, if you’re test­ing hello.html, go to http://localhost/hello.html from the machine run­ning the serv­er, and http://123.456.7.89/hello.html from any exter­nal devices you want to debug.

On the machine run­ning the serv­er, open the debug­ging client by going to the URL http://localhost:8080/client/#anonymous. In the sec­tion called Tar­gets you’ll see a list of devices that are cur­rent­ly vis­it­ing your test page. If there are mul­ti­ple devices, choose the one you want to debug — it will be high­light­ed in green. You can now begin to debug your page using the built-in tools, which are based on the WebKit inspec­tor (regard­less of the brows­er you’re using).

Next steps

Once you’ve got weinre up and run­ning I sug­gest you read through the full doc­u­men­ta­tion to get the most out of it — espe­cial­ly regard­ing set­ting up a serv­er prop­er­ties file for mak­ing weinre eas­i­er to run, or to get the book­marklet which removes the need for includ­ing the script in your doc­u­ment head.

And if you’re doing sub­stan­tial mul­ti-device test­ing you may want to look at a way of keep­ing 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 impor­tant­ly, make sure you get a deep under­stand­ing of how the web inspec­tor tools work to real­ly get the most from your debugging.

5 comments on
“Remote debugging with weinre”

  1. You saved my night! thanks :)

  2. Since Weinre attach­es itself to the tar­get HTML doc­u­ment via JavaScript, it is unable to catch events and errors that hap­pen before it is loaded. Thus, the Net­work and Time­line pages are not much of use, and the Resources page only shows lim­it­ed data.

  3. @Ropo: Sure, and most mod­ern tools are bet­ter; But if you want to debug old­er Android, for exam­ple, it’s still a good option.

  4. Very help­ful, thanks

  5. Thanks, that’s great for debug­ging Android stock browser.