Debugging mobile web applications remotely with WEINRE

I started mobile web development around eight months back and at times found it very difficult to debug my apps. Normally everybody would start off with a desktop browser, look up the app in a desktop web inspector and then try to debug it and finally make it ready for the mobile browser. Even I used to do the same. I used to check my mobile app in Chrome’s/Safari’s developer tools. There I used to inspect HTML elements, change DOM style properties and check the result out and also see the java script console log messages in the console tab. This would normally serve my purpose but I had to adjust a lot due to resolution differences. Still there was a frustration and a feeling of had there been a tool to directly debug the app in the mobile device itself. And after a little head scratching and Googling I discovered an open source package called Weinre – Web Inspector Remote. With Weinre I could debug my mobile web app remotely – the app would run on the mobile browser and I could modify the DOM remotely, see log messages of it on the Weinre inspector that runs on my computer. And I must tell you, it has helped me immensely. It’s a wonderful tool to have and in this tutorial I will share my experiences of debugging with Weinre. First I will start off with How to configure Weinre and then talk on debugging a mobile web app, but before that let’s see some basics – Weinre and its components.

The Basics
Weinre is a remote debugger for web pages and if you are familiar with Firefox’s Firebug or Google Chrome’s Web Inspector, then you will find Weinre very similar. What it means is that you can debug a web app that is running on your mobile device remotely i.e on your computer. So, in your computer you can select any DOM node, make changes to style properties of the mobile web app and it will reflect in the mobile device on the fly. You will get more familiar with the things once I talk in details later in the article. First let’s see what Weinre is composed of.
Weinre consists of three basic components/programs – Debug Server, Debug Client and Debug Target interacting with each other. Let’s see what each of them means,

1. Debug Server: This is the HTTP server that you run from the weinre.jar file. It’s the HTTP server that’s used by the Debug Client and Debug Target. I configured the server on a Windows machine so all the steps I will talk about are in reference to Windows. For Mac users details of configuration can be found in the Weinre site.

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

3. Debug Target: This is your web page that you want to debug running on the mobile device – iPhone, Android phone or iPads.

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 image below should help you.

Click for larger size
Weinre components


Configuring and running the Weinre debug server
Weinre works with web-kit based browsers, hence it is suitable for debugging web pages and web apps in iOS and Androidmobile devices, and that’s where the good thing is. Even the debug client interface works only on a web-kit based browser. So, if you open the debug client in Firefox or IE, it will not work. Try using Chrome or Safari. Let’s now talk on how to configure it and run the server.

Weinre needs Java to run. So if you do not have Java installed, get the latest version of the SDK. Once installed, follow the steps mentioned below. Remember that I configured Weinre on a Windows machine so the steps are tightly coupled to Windows. For Mac users see the Weinre site.

1)    First, download the Weinre jar file. Go to https://github.com/callback/callback-weinre/archives/master and download the zip file. Unzip it and you should find a jar file –  weinre.jar.

2)    Set the Path in Environment variables to the bin folder of your java installation directory. For me it was: C:\Program Files\Java\jdk1.6.0_31\bin. This will ensure that you can directly run a java program from anywhere on the machine. You need not specify the path of the java executable every time you run a java program.

3) Start the Debug server – open your command prompt and execute the following command

java -jar path/to/weinre.jar –boundHost ipaddress

and you should see a message like this

Click for larger image
Debug Server started

Note the path that I have set in the command. You need to give the absolute path to your weinre.jar file. For me the command I used was:

java -jar D:/Weinre/weinre-jar/weinre.jar –boundHost 192.168.30.146

where the ip address value is that of my laptop. You have to specify your machine’s ip address so that the debug server is bound to your machine. There are lot of configuration options available for the command, you can check that out here. For now, I will explain what I did to start my server successfully.

4) What is boundHost? Well, it is used to bind the debug server to an ip address or a machine. The machine will be a desktop/laptop computer. A value of –all- specifies that it will be bounded to all possible interfaces including the computer on which the server is running. You can also specify the ip address of your computer to bind it to the debug server so that it can be accessed from other devices for e.g. the mobile device. This is what I did. Default value of boundHost is localhost. If you specify localhost then you won’t be able to access the server from any machine/device other than the one the server is running on.

5) If you see the command prompt image above you would notice a port number 8080. This is the port at which the server will listen to. This is the default value. You can also specify a port explicitly by using the httpPort option for the command. I did not specify any value so by default the server runs on 8080.

6) The debug server is up and running now. To stop the server press Control – C. This will kill the process.

Running the Debug Client
Open Google Chrome or Safari and type this URL http://your-ip-address:8080 and you would see something like the image below, this is the debug client home page. Opening of this page also ensures that your debug server is running.

Click for larger image
Debug Client Home - open only in web kit browsers e.g. Chrome

Now to open the debug client click the first link under Access Points. This will open up an interface which is very similar to the Chrome or Safari web inspector. Well, this is the debug client. This is where you will inspect HTML element, modify the DOM and check out console logs. The client looks like the image below

Click for larger image
Debug Client

You must be familiar with this isn’t it. The Elements tab will show the DOM once the target is connected. Also you can see java script console messages in the Console tab. Now, to start debugging we need to connect our target device, in this case the mobile device to the Debug Server.

Inject debug java script into the web page to act as Debug Target
To make your web page debuggable with Weinre you have to inject a script into your code. If you see the Debug Client Home page you will find Target Script section. There the server has specified a script to be used in your code. Copy the <script> block and paste it in the head section of your web page that you want to debug.

Click for larger image
Target Script - paste this in the head of your page

This particular link is based on my ip address and the port I used for the Debug server. For you it will give you hardcoded set of values. So you only need to copy it.

For my demo I chose one of my example codes – the collapsible panel that I developed earlier. It has only one index.html file where the widget is built. I wanted to debug it (the page) in my iPod itself. So I copied the <script> and pasted it in the head section of the index.html file.

<!DOCTYPE html>
<html>
<head>
<title>CSS3 Collapsible Panel</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0"/>
<script src="http://192.168.30.146:8080/target/target-script-min.js#anonymous"></script>

Now that the target script is copied, I launched the collapsible panel example in my iPod browser. Note that I am using an Apache server as my HTTP server which is hosting my example codes. So I will open my collapsible panel example by directing my iPod browser to the Apache server location of collapsible panel.

Open the page in your mobile device
Open the page in your mobile device

Now that the target is ready for debugging, reload/refresh the Debug Client page in your computer and you would see the two connect. A green message would appear like the image below. Under Targets you can see your target device. If it does not happen in one go, reload the target page in your mobile device and also reload the Debug Client in your computer. The two should connect now.

Click for larger image
Debug Client showing target connections

How to debug?
Now that the Debug Target (the page running on the mobile device) is connected to the Debug Server and the target has been listed by the Debug Client you can start debugging your code. Click on the Elements tab in the Debug Client and you will see the DOM structure of your example. The image below shows my collapsible panel DOM.

Click for larger image
Page DOM shown in Debug Client Elements tab

Take your mouse over any element and you would see it being highlighted in your mobile device. Like in my case the content div is highlighted in my iPod browser.

Click for larger image
Content div highlighted in Debug Client

Change any style or DOM properties in the debug client and this would reflect in the mobile browser. As an example I changed the height of the mainHolder div element from 200px to 120px and I could see the changes happen simultaneously in my iPod browser. The two images below shows the session

Style Change
Changing the height in Debug Client
Change of height reflected in mobile device
Change of height reflected in mobile device

This way you can modify the DOM, change styles and directly see the results in your mobile browser.

See console messages
The Console tab shows you all the java script console log messages and this helps in debugging java script code. As an example I inserted console log messages in my script and when I executed it I could see them in the Console tab of the Debug Client.

if(expandCollapseBtn.src.search('collapse') !=-1)
{
  mainHolder.style.height = "30px";
  content.style.display = "none";
  console.log("----Collapsed----");
}
else
{
  mainHolder.style.height = heightValue + "px";
  console.log("----Expand----");
}
See console logs in Debug Client Console tab
See console logs in Debug Client Console tab

Conclusion
Weinre is a great tool to have in your armour. It is a complete debugging package for your mobile web applications. May be this post on Weinre is a little late, but nevertheless I hope this will help you.
You can debug applications even from your Android device browser, in fact Weinre supports all those targets that runs web kit based browsers including simulators. There are many important points that I did not cover in this tutorial. You can see all of them in the Weinre home page. Till then I will continue to explore further with Weinre.

Updates
Weinre docs and the site has moved from its previous base (Github) to the Apache servers. Here is the new link: http://people.apache.org/~pmuellr/weinre/

And the documentation can be found here: http://people.apache.org/~pmuellr/weinre/docs/latest/

14 thoughts on “Debugging mobile web applications remotely with WEINRE

  1. Have you tried installing device simulators? Weiner seems like a lot of unnecessary steps when you can access the simulators directly.

  2. Thanks for the info on getting it to work on a windows machine.
    Excellent – now I can try and find that annoying bug on Android phones which does not show up on other devices. Its a great resource so much easier than hooking up to the adb and logcat and with many more options – thanks

    • Hi Simon…….thanks…….I also looked at Adobe Shadow…….its another good tool to debug mobile web apps remotely in iOS and Android devices. You can give it a try. I am also writing a post on it.

  3. […] http://people.apache.org/~pmuellr/weinre/docs/latest/ (weinre home)http://people.apache.org/~pmuellr/weinre/builds/ (downloads)https://groups.google.com/forum/?fromgroups#!forum/weinre (Weinre Google Groups)http://muellerware.org/papers/weinre/manual.html https://jbkflex.wordpress.com/2012/04/12/debug-mobile-web-applications-remotely-with-weinre/ http://techblog.hk.agenda-asia.com/2012/03/07/weinre-remote-debugger-for-mobile-web/ http://hiediutley.com/2011/11/22/debugging-ios-apps-using-safari-web-inspector/ http://www.youtube.com/results?search_query=weinre  Share this:FacebookTwitterMoreDiggStumbleUponRedditEmailLike this:LikeBe the first to like this. […]

  4. Howdy! Would you
    mind if I share your blog with my myspace group? There’s a lot
    of people that I think would really appreciate your content. Please let me
    know. Thanks

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s