weinre - Running

This page describes how to use weinre to debug your own web pages on a remote device.

First, some background.

Terminology

When using weinre, there are three programs interacting with each other.

Debug Server

This is the HTTP server that you run from the weinre-node distribution. It's the HTTP server that's used by the Debug Client and Debug Target.

Debug Client

This is the Web Inspector user interface; the web page which displays the Elements and Console panels, for instance.

Debug Target

This is your web page that you want to debug. This name (Debug Target) is also used to refer to the machine running the browser displaying the web page. Since a design point of weinre is to allow debugging applications on mobile devices, the debug target, when speaking of the machine, is your mobile device.

Both the Debug Client and the Debug Target communicate to the Debug Server via HTTP using XMLHttpRequest (XHR).

Typically, you run both the Debug Client and the Debug Server on your desktop/laptop, and the Debug Target on your mobile device.

The Debug Target is the squirrelliest bit. You will need to arrange to inject some JavaScript code, provided by the Debug Server, into your web page, in order for it to function as a Debug Target.

Running the debug server using an npm installation

To run weinre from an npm installation, assuming you've installed it globally (in the npm sense), execute the following command:

weinre [options]

The server will run until you kill it. Control-C will do the job.

Options available are:

• --help (or -? or -h)

  Display this help.

• --httpPort [portNumber]

  The port to run the HTTP server on.

  Default: 8080

• --boundHost [hostname | ip address | -all-]

  The ip address to bind the server to.

  Default: localhost

  With the default of localhost, you won't be able to access the server from any machine other than the one the server is running on. You will need to bind to another hostname / ip address to make the server accessible to other machines. You can use the value -all- to indicate that you want to bind to all interfaces available on the current machine.

  Use ifconfig on Linux or the Mac, and ipconfig on Windows, to get the ip addresses available on your machine.

• --verbose [true | false]

  Causes jibberish to be written to stdout

  Default: false

• --debug [true | false]

  Causes even more jibberish to be written to stdout

  Default: false

• --readTimeout [seconds]

  The number of seconds the server will wait for a message to be available to send to the target or client.

  Default: 5

  Can probably be set larger, but then your browser may time out. Probably don't want to set it much lower than this as it will cause additional network traffic when no messages are being sent (it will cause more "empty" messages to be sent).

• --deathTimeout [seconds]

  The number of seconds to wait to hear back from a debug client or target before declaring them dead.

  Default: 3 * readTimeout

  Normally the default will be fine. However, if you're debugging weinre itself, you may wish to set it much longer.

The ~/.weinre/server.properties file

You may also create a file named server.properties in the directory .weinre in your home directory (eg. ~/.weinre/server.properties). Your home directory is the determined by the value of either the HOME or USERPROFILE environment variable.

The keys should be the same as the name of the options above, with the same values.

As an example, your ~/.weinre/server.properties file might look like this:

boundHost:    -all-
httpPort:     8081
reuseAddr:    true
readTimeout:  1
deathTimeout: 5

Command-line options override the options specified in the ~/.weinre/server.properties file.

Running the debug server bound to something other than localhost

Since the web page you want to debug (the debug target) is probably running on a different machine (your mobile device) than the debug server (your desktop / laptop), you can't use the default localhost value for the --boundHost option. Instead, you will need to specify a host name / ip address with the --boundHost option. This host name / ip address must be accessible to the machine you want to use as the debug target.

To get started, you can use the value -all- for the --boundHost option.

Now you'll need to figure out what host name / ip address the debug target should use. If you've use the --boundHost -all- option, then bring up the debug client using the URL http://localhost:[portNumber]/client/ from the same machine the debug server is running on. On that page, under Server Properties, is a list of bound hosts that the server believes it's available on.

From the debug target device (eg, your mobile device), try accessing the server home page from all of those host names, using the URL http://[host name / ipaddress]:[portNumber]/. Once you find one that displays the server's home page correctly, remember that host name / ip address, we'll be using it in a minute.

Instrumenting your web page to act as a debug target

At this point you now have a URL to the debug server which will be accessible from the debug target. Let's say that URL (to the debug server's home page) is: http://a.b.c:8081.

To make your web page debuggable with weinre, add the following line to your web page:

<script src="http://a.b.c:8081/target/target-script-min.js"></script>

You can now open a debug client by browsing to http://a.b.c:8081/client (or probably http://localhost:8081/client as well) on your desktop/laptop, then reload your newly instrumented web page on your mobile device, and see the two connect in the Remote panel of the debug client.

Hardcoding host names / IP addresses in your web page?

Yeah, gross.

Besides being gross, there are a few practical problems with hardcoding the debug server address in your web page as well:

• Your html file is probably stored in an SCM, and you don't really want to be storing that address in the SCM. It won't work for other people using that html file, for instance.

  But you don't want to be keeping the <script src=""> line in your SCM either. You should look for a way, as part of your personal build process to add that line only for development builds, and presumably with a user-customizable URL.

• The URL the debug server runs on may be different depending on your location. At work, you may use one IP address and host name; at home, you likely have a different IP address and host name. You may not have a host name at all, just an IP address (which is fine - a host name isn't required, but usually makes things easier). You may be running on a dynamically assigned IP address, in which case your IP changes every time you log into your network.

  One way out of the dilemma is to use a dynamic DNS solution for the the machine you run the debug server on. Doing a web search on the following terms will provide you some links to such services: dynamic dns static hostname

  If you use one of these dynamic DNS services, you can arrange to use the same host name for your debug server no matter what network you are connected to.

Using a bookmarklet

Some platforms support 'bookmarkets', which allow you to inject arbitrary JavaScript code into any web page running in your browser. Mobile Safari is one of these browsers. It appears that the browser shipped with Android 2.2 and later also supports bookmarklets.

Unfortunately, installing bookmarkets on mobile devices isn't usually trivial. The easiest course of action is to add a new random bookmark to your bookmarks, and then edit it by hand to change the label and URL. The URL you should use is available in both a 'pre' and 'textarea' section of the server's home page (eg, http://localhost:8081/). You should be able to select the text from one of these areas easily, to paste into the previously added bookmark.

Once the bookmarklet is installed, you can debug any web page by visiting it, and selecting the bookmarklet from your bookmarks menu.