Best Practices for Debugging Cross-platform HTML5 Applications

The Intel® HTML5 Development Environment - BETA provides a set of testing and debugging tools that help you ensure that your apps work well across all your target execution environments. This document describes best practices for how to use these tools to maximize your productivity. Each tool provides a different execution environment with differing tradeoffs between capabilities, convenience, and fidelity to target execution environment. Start with the most convenient and powerful environment, find as many errors as possible, then move on to higher-fidelity environments where more defects can be found.

The debug and test process is somewhat different for different kinds of HTML5 applications. Some HTML5 applications only use standard web APIs that are available in a browser. Other HTML5 applications, called hybrid web applications, use additional APIs such as the Apache Cordova* API to access on-board device resources such as cameras, sensors, and device data stores. Hybrid web applications require a test environment that supports the API. Other applications can be tested in host and target browsers. Throughout this document, "host" refers to your development machine, where you are running the Intel HTML5 Development Environment, and "target" refers to the environment where your application is executing.

Here is a list of test and debug tools, introduced in the order in which they should be used.

Previewing in the Host System Browser

This operation is supported within the IDE using the Tools>Preview in Browser menu item. This simply opens a new browser tab that displays the currently selected project HTML file. Unfortunately preview has limited usefulness for hybrid web applications because there is no support for non-browser APIs.

This approach is very familiar to those of you who come from a web development background. You can test your applications core functionality in the comfort of your host machine. You can also utilize browser-based utilities like Selenium, which lets you record and run automated tests.

In the Preview environment, you can use the powerful built-in debugging tools for your browser. The Google Chrome* browser provides Chrome developer tools. Full JavaScript language debugging is available. You can set breakpoints, single step and display variables in your JavaScript code. You can also do full Document Object Model (DOM) debugging. That is, you can display the HTML elements that are being rendered, see their relationship to the display, and set breakpoints on DOM events. You can also see the effects of CSS on the DOM. Additionally you have access to a JavaScript console, from which you can view your application's console.log messages and dynamically interact with your app by entering any JavaScript command.

You can get a cursory feel for how you application may look across different screen sizes by tearing off the preview tab (click the tab and drag it off the browser's window) and trying out various sizes. Note that the host system browser may display a vertical or horizontal scrollbar but a mobile browser would not.

Running in the Device Emulator

The Intel HTML5 Development Environment provides a Device Emulator that retains the conveniece and capabilities of in-browser previewing, while providing emulated device capabilities and support for hybrid web applications. Launch it using the Tools > Device Emulator menu or by clicking the  icon on the menu bar. See the Getting Started Guide: Intel HTML5 Development Toolkit/Device Emulator for information about the Device Emulator.

Begin by selecting a virtual device and virtual platform.

Selecting a virtual device determines the size of the frame rendering your application. You can also change the orientation from portrait to landscape mode. By selecting different devices and orientations, you can quickly see how your application looks and behaves in a variety of screen sizes and aspect ratios.

Selecting a virtual platform determines what cross-platform APIs are available. For hybrid web applications, choose the Cordova 2.0.0 platform.  Otherwise select Mobile Web

The rest of the Device Emulator UI consists of panels that allow you to configure the virtual environment seen by the application under test. For example, the Geo Location panel allows you to select the location returned to the program under test when it invokes the API that requests the current location.

An example may explain the difference between running an application under the Device Emulator versus Preview in Browser. Suppose you have an application that requests the currently location through the geolocation API. When previewing, requests to obtain the current location are handled in the browser environment. Geolocation is now a W3C standard, so it is implemented by many browsers. If your browser supports geolocation, then this either returns the true location of the host system or (if you deny access) a PERMISSION DENIED error. If your browser does not support geolocation, your application might get a JavaScript exception such as "call to undefined value". When using the Device Emulator, requests to obtain the current location are handled by a simulation that returns the location selected by the Geo Location panel. This allows you to test your application's behavior at any location without moving your host system.

As in the Preview environment, you can fully debug your application using the browser’s debugger. However, when you run Chrome developer tools within the Device Emulator, you see both your code and the implementation of the Device Emulator itself. This can be a little distracting, but with a few tricks it is possible to focus on your own code. See the Getting Started Guide: Intel HTML5 Development Toolkit/Device Emulator for more details and best practices.

Running on Real Hardware

Running your HTML5 application on real hardware allows you to see your application exactly as your users will see it. This is the only test environment that reveals performance issues, such as slow scrolling. Running on real hardware is quite different for pure web applications than for hybrid web applications.

You can easily run a pure web application on a target system browser. The cloud-based IDE acts as a web server that hosts your application. Simply direct your device browser to the same URL that appears when you preview the app. Please note, however, that your device browser cannot access the project files served by the IDE without first logging into the IDE, because your files are private. To gain access, direct the device browser to the Intel® Developer Zone (Intel® DZ) portal and login. Once you have successfully logged into the developer zone, you should be able to access your project files. Do not run the IDE itself on your mobile browser.

Tip: Use the Tools > Show Preview URL as QR Code menu in the IDE to expose the preview URL for your application. Scanning the QR code with your mobile device saves you the trouble of typing in the URL. Once you have reached the URL for your application, set a bookmark. The URL will not change.

As with Previewing in the Host Browser, this approach has limited usefulness for hybrid web applications because there is no support for non-browser APIs.

To run a hybrid web application on real hardware, you must first package your application with the PhoneGap Build utility (or some alternative build utility that supports the Covdova API). See the Intel® HTML5 Development Environment Getting Started Guide for more details about how to do this. Once your application has been packaged by the PhoneGap Build utility, you can download it to your mobile hardware using the QR Code feature of PhoneGap Build.

Debugging on Real Hardware

Most mobile devices have no screen space available for a practical debugger user interface. Thus you can be reduced to print statement debugging unless some kind of remote debug solution is available.

Remote debugging means you debug code running in the target system using a debugger that runs on the host system. The debugger on the host controls and examines the target system using a communication link, often over a wireless connection or a USB cable. Remote debugging allows the debug UI to escape from the display limitations of the target environment and minimizes the debug footprint on the target device. Remote debugging offers the same capabilities as debugging in the host system browser.

There are a number of limitations on remote debugging. If you find yourself in a situation that does not support remote debugging, you can achieve a partial form remote debugging through the weinre tool.  We will describe weinre in more detail below.

Most of the newest target system browsers support remote debugging. On Android 4.0 (Ice Cream Sandwich) or later you can debug using Chrome for Android on the target with Desktop Chrome on the host. On iOS 6.0 or later, you can debug using Apple Mobile Safari* 6 on the target and Desktop Safari 6 on the Mac host. You can also debug using Opera Mobile* 12 or later on the target and Opera 12 on the host, and on Mozilla Firefox* 15 or later on the Android target and Firefox 15 on the host.. Unfortunately these implementations do not interoperate; Chrome only works with Chrome, Safari with Safari and so on. Except on iOS version 6, remote debugging is not supported when the application is running in a PhoneGap Build package and therefore cannot be used for hybrid web applications.

The procedure used to establish a remote debug session varies from browser to browser, and may require installing additional tools. See the following links for instructions for Chrome, Safari, and Opera.

Using Weinre

If remote debugging is not available your next best alternative is weinre, which stands for Web Inspector Remote. Weinre provides a subset of the capabilities of remote debugging; in particular it does not support JavaScript debugging (set breakpoint, single step, etc.).  It can, however, access the DOM rendered in the target system and capture console output.

Weinre consists of three interacting components.  The first component is called the debug agent.  This consists of JavaScript code that must be injected into your application so it can be debugged. The second component is the weinre debugger user interface that runs in the host browser. This is similar to the user interface for Chrome developer tools. The third component is the debug server, a stand-alone program used to connect the debugger user interface to your application in a secure way.

See the weinre documentation home page for instructions on how to install and use weinre. This explains how to install and execute the debug server.

There are two ways to inject the weinre debug agent into your application.  You can edit your HTML5 program to add a <script> tag to bring in the weinre debug agent. If you use PhoneGap build, you can request a "debug build" from the PhoneGap Build service that automatically injects the weinre debug agent into your application during packaging. PhoneGap build also provides a debug server you can use instead of running your own. See the debug build section of the PhoneGap Build documentation for more details.

Once the debug agent has been injected and the debug server is running, the last step is to connect the debugger with the program under test. The exact process used depends on which debug server you are using. See the weinre documentation home page or the debug build section of the PhoneGap Build documentation, as appropriate.

Running in Platform-level Simulator

The platform-level simulator is a software simulation that runs on the host system and can execute (almost all of) the real target system software. This provides a quite accurate impersonation of the real target system environment, because you are executing the real target system code, quirks and all.The main advantage of the platform-level simulator is that it allows you to test in lots of different environments with greater fidelity than the device emulator without having to use lots of real test devices.

The platform-level simulator is typically a component of the platform software development kit (SDK); it is not included in the Intel HTML5 Development Environment - BETA. You must install the platform SDK to use the platform-level simulator.

The platform-level simulator also provides a valuable last resort if your application works under the device emulator and fails in a non-debuggable way on real hardware. Such situations are rare in HTML5 application development, but it's good to know this resource exists if you need it. The platform-level simulator is very useful for debugging native code, but cross-platform HTML5 applications should not use native code.

Platform-level simulators generally come with debugging tools of their own, but these are often not HTML5-aware the way that browser-based debuggers are. You can apply the same HTML5 debugging techniques described above for debugging on real hardware when running in a platform-level simulator.

Some platform-level simulators imposes a significant performance penalty. This can occur for example if the platform-level simulator executes target machine instructions intended for an ARM processor on a host machine containing an x86 processor. Time-sensitive applications, such as various games, often cannot execute in a simulation environment like this.

Summary

Tool

Supports Hybrid Web Applications/Cordova API

HTML5 Debugging Assistance

Accurate Layout

Accurate Behavior

Accurate Performance

Preview in Host Browser

No

Yes

No

No

No

Device Emulator

Yes

Yes

Yes

No

No

Mobile Browser on Real Hardware

No

Yes if remote debug is available; use weinre for partial debugging

Yes

Yes

Yes

PhoneGap Packaged App on Real Hardware

Yes

No

Yes

Yes

Yes

PhoneGap Debug Packaged App on Real Hardware

Yes

Use weinre for partial debugging

Yes

Yes

No, but close

Platform-level Simulator on Host

Yes

Yes, if remote debug is available; use weinre for partial debugging

Yes

Yes

No, and may be slow

Para obtener información más completa sobre las optimizaciones del compilador, consulte nuestro Aviso de optimización.