Just as debugging should be thought of as a vital part of every development cycle, on-device debugging should be part of any effective testing regimen. Although much can be accomplished using emulators and an IDE, applications often behave differently when running on hardware, and features such as Barcode scanning are impossible to test without the use of physical hardware to perform the scan and acquire the data.
This guide includes instructions for enabling debugging on an Android device and describes two methods of debugging Enterprise Browser apps while they're running on a device:
Weinre - is a node.js application that can effectively test most apps running on Android Jelly Bean as well as Windows Mobile/CE devices.
Remote Debug Inspector - works with Windows Mobile/CE devices that use the Zebra Webkit.
Requirements of the development host vary based on the target device and its OS platform. General requirement guidelines are listed below. Platform-specific requirements, if any, will be listed in the section that describes the individual debugging tool and/or method.
- Mac OS X or Windows development host
- Android Debug Bridge (ADB) or MS Mobile Device Center (or ActiveSync)
- Chrome 32 or later (Chrome Canary recommended)
- A Zebra target device (Android or Windows Mobile/CE)
- A USB cable for connecting the target to the dev. host
- USB debugging enabled on target
- A WebView-based app configured for debugging
This section of the guide follows a 14-minute Weinre webinar and uses the Barcode Example app from that lesson for all of the examples in this guide. You're welcome to download the app and follow along, use your own app, or simply play around with the APIs and code snippets.
Note: Admin/sudo privileges are required to install Weinre.
Weinre is a Node.js application and is delivered via a Node Package installed with the
1. Download node.js from the project's
2. On Windows, install Weinre using the following command:
$ npm -g install weinre
Mac users might need to include the 'sudo' prefix:
$ sudo npm -g install weinre
For more information about installing and configuring Weinre, please refer to the Weinre installation site.
IMPORTANT: The target device must be on the same Wi-Fi network as the development host. When launched, Weinre must be bound to that network using the
boundhost parameter (see below). Launching without this parameter will bind Weinre to the
localhost, making it inaccessible from the device.
3. Launch Weinre from the command line using the
$ weinre --boundhost <development host IP address>
Weinre will respond with a message similar to the one below--an address and port that will be used to communicate with the device:
2013-10-31T00:24:07.549Z weinre: starting server at http://192.168.1.128:8080
4. Using a browser, open the address and port provided by Weinre.
The page should look something like this:
Click on any image to enlarge.
If all has gone well so far, the browser is displaying the Weinre Inspector Remote console. In the section labeled ‘Target Script,’ there's a string that contains a URL with the dev host's local IP address and port number, plus the name and path of the script file that Weinre needs to communicate with the target device.
Lower in the Target Script section is an example of how to embed the Target Script string between script tags:
Example Script String:
<script src="http://<your local ip address>:<your port>/target/target-script-min.js#anonymous"></script>
5. Copy and paste the example script string (above) into the*
barcode_enumerate.html *file (or your corresponding app file).
6. Copy the URL string referenced earlier and use it to replace the example URL. Be sure to leave the quote marks on either side of the URL.
The line in the HTML should look like this:
7. Start the Weinre debug UI by clicking the link in the Access Points section of the Weinre browser page:
The image below shows the ‘Remote’ tab of Weinre’s Debug Client UI. The ‘Targets’ and ‘Clients’ sections contain one device each, and the green text indicates that both devices are communicating.
The inset image is a screenshot from the target Android device that’s being displayed by an app called Droid@Screen . This useful screencasting tool uses USB and ADB to stream screen shots to the development host.
At this point, the app can be inspected as with the web inspector of Chrome or any other tool. The Elements tab shown below demonstrates two-way communication between the device and the development host. Clicking on an element in the HTML will cause that element to be highlighted on the device’s UI.
The Elements tab can be used for on-the-fly changes to CSS styling, API and method calls and any and all app UI settings. In the example below, the button text was changed from ‘Enumerate’ to ‘Changed!’ simply by editing the test in the Elements tab.
Button text "Enumerate"
Button text "Changed!"
One of the most versatile components of Weinre is its Console. Not only does it offer classic capabilities such as device visibility and monitoring during operation, but the Weinre Console also can access all of a device’s hardware features, issue commands and report how the device reacts.
Here’s another important benefit of the Weinre console.
Notice that when the barcode callback handler function is executed, we are using the form
e is the callback return object. This allows us to inspect the object right in the console. It also simplifies validation because we see that it contains a barcode property and a status property, exactly as described in the Barcode.take( ) method description. Alternative means, such as adding code for outputting to a log and then searching and retrieving the information from the device, can be time-consuming and error-prone.
Several other tabs in the debugging UI can be quite useful.
The Timeline tool measures and displays the rendering time of each element of the user interface, presenting a visual display similar to that of the Network tab. The Timeline tab is useful for finding bottlenecks in front-end UI or DOM performance.
More information about Timeline can be found starting at 25:10 of Zebra’s Front-End UI Optimization Webinar. This one-hour video contains useful information about detecting re-flows and other common problems that can bring mobile apps to a crawl.
The Remote Debug Inspector tool is for debugging apps running on Zebra Windows Mobile/CE devices that use Zebra Webkit. Remote Debug Inspector installs on the device and requires a new tag in the Config.XML of the target app to make it work with desktop Chrome.
- A Mac (with ADB) or Windows 7 or later PC (with Mobile Device Center)
- Enterprise Browser installed on the development host
- Chrome browser installed (Mac or Windows)
- A Zebra device running Windows Mobile/CE
- An EB app installed with Webkit (not the IE Engine; see below)
- A connection to the device for copying files (Bluetooth, USB or Wi-Fi)
- The development host and device on the same subnet (over which to debug)
Enterprise Browser device installer showing Webkit deployment options.
Click on any image to enlarge.
1. Download Remote Debug Inspector tool.
2. Copy the downloaded
"inspector.CAB" file to the device.
3. Execute the file, which will install into a folder called
/inspector on the device.
4. Add to the Config.XML file (of the target app) the following tags:
... </HTMLStyles> <RemoteDebug> <ResourceFiles value="file:///inspector/"/> <ServerPort value="7000"/> </RemoteDebug> <SIP> ...
Notice that the <RemoteDebug> section is inserted after <HTMLStyles> and before <SIP>.
Also note that we're using the default values for ResourceFiles and ServerPort. If these are changed, be sure to make the corresponding changes in the next steps.
5. Note the IP address of the target device (Wi-Fi Settings >> Wi-Fi Driver Settings). It must be on the same subnet as the development host.
6. Launch the Enterprise Browser app to be tested.
7. Enter the following URL in Chrome's URL bar:
... http://<device ip address>:7000
After a few moments, the browser should display a page similar to the image below:
8. Click on a link to inspect it in a panel similar to the image below:
This panel works in much the same manner as those of Weinre and Chrome Web Inspector (click on any image to enlarge).