EnglishJapanese

Weinre

The open-source Weinre project is available for remotely debugging Javascript applications. A Weinre instance is hosted on PhoneGap Build, or you can run your own instance locally:

• Using PhoneGap Build's Debug Server
• Running your own local Debug Server

PhoneGap Build Debug Server

This section shows how to use standard Web Inspector tools available from the PhoneGap Build site to debug PhoneGap apps while they are running on your device. See the PhoneGap Build section for details on how to provide the site with project code, and how to get the resulting compiled apps onto your device.

To enable debugging from within the list of existing Apps, click on the name of the application to view its details. Click on the Settings tab, then select the Enable debugging check box:

Once the debugging option is selected and you build the project, the Debug button appears along with other options to update code and rebuild the project. When you preview the app on the device, perhaps by scanning the QR code as described in the PhoneGap Build section, pressing Debug opens a web page that allows you to communicate with the app as it runs on the device:

Pressing the listed target gives you access to the app's internal state. The debugger may occasionally lose its connection if you pause the app or if the device goes into a standby mode. In that case, the Remote tab may present a new target with which to re-establish the connection.

Once connected, the Elements tab allows you to view the app's full DOM tree as it executes:

You can use this interface to modify the application as it runs. For example, the default PhoneGap app generated by the CLI (see The Command-line Interface) presents a slowly blinking status message beneath the icon:

Selecting various elements from the DOM tree in the debug view highlights them on the device if visible, which may help you locate the relevant code:

<div id="deviceready" class="blink">

The sidebar on the right allows you to view information about CSS properties applied to each element and the selectors that specify them. If you double-click on the class attribute and delete the blink text, the message stops blinking on the device, and the .blink selector disappears from the sidebar's Matched CSS Rules:

.blink {
  -webkit-animation: fade;
  -webkit-animation-delay: initial;
  -webkit-animation-direction: initial;
  -webkit-animation-duration: 3000ms;
  -webkit-animation-fill-mode: initial;
  -webkit-animation-iteration-count: infinite;
  -webkit-animation-name: fade;
  -webkit-animation-timing-function: initial;
}

To see the same change without editing the DOM, select the Console tab and type a JavaScript call directly onto the command line. This example selects the element whose id is deviceready and turns on or off its blink class:

document.querySelector('#deviceready').classList.toggle('blink')

The method's return value displays within the console. Typing the name of any object allows you to view its evaluated contents:

The browser engine's error messages and results of console.log() calls also appear on the console.

Navigating back to the Elements view displays the results of the change, but note there may be a delay, and you may need to re-select the DOM node to view its current state.

The Web Inspector offers several other useful features:

• The Network tab lists details on network requests the app makes while executing, along with a timeline interface to visualize a progression of network interactions.

• The Timeline tab similarly visualizes load times for the app's component resources.

• The Resources tab allows you to inspect cookies and the contents of various client-side databases (localStorage, sessionStorage, Web SQL) set by the Storage API. Note that this view also allows you to inspect the HTML5 Application Cache, which allows you install an app persistently from a set of network resources. However, this feature is less appropriate for PhoneGap apps, which are already delivered to the device as part of an installed native package.

Despite slight differences in how Web Inspector features appear in different WebKit-based browser environments, the documentation for Google Chrome and Apple Safari provides a good overview.

Running a Local Debug Server

PhoneGap Build allows users to use their own debug server with the Build service.

Build uses a tool called Weinre to enable remote debugging of mobile apps.

This guide provides information on setting up your own local server.

The pre-requisites for running Weinre are that you need to have npm installed. Once you've installed Weinre you will only be able to use the local server within your own network unless you plan to host it on a publicly accessible location. This will require additional setup that is outside the scope of this guide.

Set Up Weinre

Once you have npm installed, obtaining and installing Weinre is as simple as running the following command in a terminal.

sudo npm -g install weinre

That's it! Now you're ready to run your very own Weinre instance.

Start Weinre

To start your new local Weinre instance run the following command:

weinre

You will now see output like the following:

Hardeeps-MacBook-Air:~ hardeep$ weinre
2013-07-01T20:03:34.890Z weinre: starting server at `http://localhost:8080`

Weinre is now up and running! If you are running this behind a router that uses NAT you will need to find your IP address. You will use this IP when specifying your configuration with Build.

Using a Local Weinre Instance with Build

Obtain the ip address of your machine running Weinre. This can be done on Windows by running ipconfig or on OSX/Linux by running ifconfig.

Now include a reference to the Weinre debug script on your debug server, like so:

<script type="text/javascript" src="http://my.server.ip/target/target-script-min.js#some_unique_key"></script>

Common Issues

I can't connect to my Local Server

First of all make sure that your server is running. Chances are if you're using the default configuration you can visit http://localhost:8080 and it should be responding.

If this works it's most likely the IP address you're providing to Build; please verify that it is correct. A google search such as windows [version] find ip address or OSX [version] find ip address will help you find articles on getting the right ip.

Assuming that you're using a router running NAT verify that you can visit it within your network by visiting http://[ip address]:8080.