Using Node weinre to Debug Cordova* Apps

For situations where you cannot use remote debug over USB to your Android device or remote debug of your iOS device over USB with a Mac and Safari Web Inspector, weinre is a useful alternate solution. Using the weinre remote console from your desktop browser provides access to a JavaScript console in your built app that is similar to the JavaScript console found in most desktop browsers. This solution does not support JavaScript single-stepping or breakpoints, and it has limited CSS debug tools.

Before you get started you may want to watch this video for a demonstration of how to use the weinre remote JavaScript console. Begin watching the video at about 14:30 for details that are specific to debugging with a local Node weinre server.

Installing a Local Node.js Hosted weinre Server on Your Workstation

Install weinre locally, on your development machine, and use weinre with your local browser. You will need to install Node.js, NPM and the weinre node app onto your development system to use the weinre debug tool.

Installing a local weinre server onto your development system involves the following steps:

Windows users may want to also (optionally) install the npm-windows-upgrade package (using the command-line, after node and npm have been installed):

These are the primary reference pages for the tools you installed above:

Starting the Local weinre Server on your Workstation

Start the local weinre server from a command-line (terminal or cmd) session using the command weinre --boundHost "my.local.ip.address" where "my.local.ip.address" is the local numeric IP address of your development machine (the machine on which you are running the weinre --boundHost command). See How to Find Your Local and External IP Address for help determining your local IP address.

For example if your local IP address is 192.168.2.12, you would type:

weinre --boundHost 192.168.2.12

at the command line to start the local weinre server.

NOTE: Your local IP address is not guaranteed to be fixed. You should double-check the value of your local IP address before starting a local weinre session, especially if your machine has been rebooted, has been asleep or has reconnected to your network since the last local weinre session.

Start the weinre local server information page by opening your favorite browser to http://##.##.##.##:8080/, where ##.##.##.## represents your local IP address (the example image below is from a system with a local IP address of 192.168.2.12):

NOTE: do not forget to switch your mobile device to your local wifi!! Your mobile test device, especially phones that can access the Internet over a cellular connection, must be on the same network as your development machine in order to see your Node.js weinre server. If your phone is connecting to the Internet via your mobile service provider it will not be able to see the weinre server, they must be on the same local network.

Open the Local Debug Console in Your Browser

Now you can open the weinre JavaScript debug console in a new tab in your browser by using the debug client user interface link highlighted in the weinre local server information page above.

This will result in a page similar to the image shown below. In this case we have not yet connected to the app on the device to be debugged, thus the reason for the message about a "lost connection." Nothing is wrong, in this case the app is not yet running, and has yet to connect to the weinre debug server running in Node.js on your development system.

Configure and Start the App to be Debugged

You must copy the target script URL from the weinre local server information page (see the image below) into the index.html file of the application you plan to debug (again, this image is from a system where the local IP address is 192.168.2.12):

If you are using App Preview you can load (using the Test tab) and start your app in App Preview to begin debugging via your local weinre JavaScript console (make sure you copied the target script tag into your application's index.html file).

If you are going to debug an app that contains third-party plugins that are not supported by App Preview, you will need to build the app (with the target script tag copied into your application's index.html file), install the built app onto your device, start your app and begin debugging with the weinre JavaScript console that is open in your browser.

Debugging a built app does not require rebuilding your app to test changes or experiment with your code. The best debugging experience will come from taking advantage of the interactive JavaScript console to redefine functions within your app and then run those redefined functions directly from the console or restart your app, in situ, using the window.location.reload() function. An example of using this technique can be seen in this video, starting at about 18:30.

Additional Notes

You may have to experiment with the best location for the weinre script tag within your index.html file. For example, whether it should go before or after the cordova.js script tag; near the beginning or end of the index.html file; etc. The optimum placement for the weinre script will vary with each app.

You can build an app and use the weinre remote console to debug that built app once it has been installed onto a real device. This is useful for tracking down issues that can only be debugged in a built app, or where no good USB debug alternatives are available (such as debugging a Windows Phone app).

VERY IMPORTANT! You should never leave a weinre script tag enabled in the index.html file of a published app. Doing so means that every instance of your app will attempt to contact your weinre server when it starts, resulting in a delayed or hung startup of your app (due to having to use the network to contact the weinre server), excessive use of your customer's mobile data and confusion.

Additional useful instructions can be found here:

Despite references to specific mobile platforms, in the links above, the basic install and application techniques described in the above articles will apply to any mobile platform.

For more complete information about compiler optimizations, see our Optimization Notice.