Fork weinre on GitHub

weinre - Running

Home - Test Drive - Installing - Running - Multi-User - Security - Building - ChangeLog - License

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.jar file or the Mac application. 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.

When using the Mac application, the Debug Client and Debug Server are running in the same process. When you launch the application, the server starts, and then the browser included in the application is launched on the appropriate URL automagically.

When using the weinre.jar program instead of the Mac application, only the Debug Server is started. You will need to launch the Debug Client in a web browser.

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.

Starting the debug server

There are two ways to run the weinre debug server:

Running the debug server using the weinre.jar file

To run weinre from the jar file, execute the following command:

java -jar path/to/weinre.jar [options]

Options available are:

You may also create a file named server.properties in the directory .weinre in your home directory (eg. ~/.weinre/server.properties). 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.

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

Running the debug server using the Mac application

Go back and read the description above about the weinre.jar settings.

Only the ~/.weinre/server.properties file is available to configure the server, as there is no traditional command line used to launch Mac "applications".

The server will run until you quit the application.

Since there is no practical way to see the stdout and stdin from the server when running a Mac application, these streams are intercepted and displayed in the Server Console tab in the Mac application.

The Mac application also displays the server's home page in a separate tab.

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.

When you run the debug server with a bound host other than localhost, by definition other machines can now access your debug server. See the Security page for information on how to protect yourself.

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:

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.

Using the target/target-script-min.js file statically

If you'd like to use the debug target code statically, instead of downloading it from the server all the time, then you will need to do one more thing. The debug target code computes the address of the debug server from the src attribute in the <script> tag, and it won't be correct in the static case. Instead you can set the following variable to be the URL of the debug server:

window.WeinreServerURL

This URL overrides what's otherwise calculated from the debug target code itself. You will need to set this value before the target/target-script-min.js script is loaded.

Future Enhancements

The calculation of the debug server url by the debug target is a bit fragile and ham-fisted. We should look at additional ways to handle this. For instance, we could prompt the user for the debug server address, and then always using the debug target in a more static mode; eg, you'd include the target-script-min.js with all your other files in your application.

Running the debug server on the target device is another option. This shouldn't be a huge problem for Android, but is more of a problem on iOS. By running the debug server on the target device, the debug target can always connect to the debug server by using a localhost hostname. The debug client, running on your desktop/laptop, would then need to connect to the target device to debug. In practice this may be an easier scenario to work with, as the potentially changing IP address of the mobile device just means having to type a different URL in your web browser on your desktop / laptop when running the debug client. That's easier than hard-coding URLs in your web page, for instance.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Home - Test Drive - Installing - Running - Multi-User - Security - Building - ChangeLog - License