Debug and Test Overview

The Intel® XDK produces standard Cordova* packaged applications (aka Adobe* PhoneGap* apps). Cordova packaged apps rely on the built-in webview of the target platform to execute your application's HTML5 code. A Cordova packaged app can be viewed as a client-side HTML5 web app that is contained within a native wrapper so it can be submitted to a native app store and installed onto a mobile device, like any other native app.

Unlike a native app, you cannot use the native debugger to debug your HTML5 code (other than logging and similar limited activities). There are a variety of techniques available to help you debug the HTML5 code in your Intel XDK [aka Cordova] app. Some are available directly in the Intel XDK and some are available using tools external to the Intel XDK. Which technique is best to use depends on a variety of factors, including:

• the target device (Android*, iOS*, Windows*, etc.)
• your development system (Windows, OS X* or Linux*)
• inclusion of third-party Cordova plugins
• workstation to device connection (local wifi, USB, Internet, etc.)
• debugging HTML or CSS or JavaScript

This article will provide you with a high-level overview of most of the techniques that are available to debug Intel XDK Cordova packaged apps and will try to guide you to the best debugging option(s) for your situation. In all cases, the specific techniques are left to other documentation and articles that contain the necessary details. To that end, use the following table to help you decide where to start:

*NOTE:Debugging apps that include third-party plugins (e.g., those that are not "included" on the Projects tab) can be accomplished using all of the techniques in this table if you restrict your debugging to those parts of your app that do not depend on the third-party plugin(s). For example, if you include code to detect the presence or lack of third-party plugin APIs and (optionally) provide "fallback" functionality for those situations (such as in the Emulate tab) where the third-party plugin API is not available.

The Emulate tab is a derivation of the Ripple* open-source Cordova emulator and is best used for quick preview and debug. Do not use it to validate your code for use on real devices or for debugging code that depends on third-party plugin APIs. Its primary value is allowing you to quickly see the results of changes you make to your project files using either your favorite code editor or the Brackets* editor that is built into the Develop tab.

It is important to understand that the Emulate tab is a Chromium* desktop browser. It does not and cannot emulate real mobile devices!! Best debugging results will be achieved by using the Emulate tab to debug non-device APIs and layout; then use a real device to debug the device-specific code in your app and fine-tune your layout.

Despite its name, the Emulate tab does not emulate real devices. It does include a simulation of the core Cordova and Intel XDK plugins (APIs) and provides a convenient collection of device viewports for previewing your app's layout. It can also simulate some key mobile device events and provides a mock userAgent string for the selected device. However, the Emulate tab does not simulate a real device; it is an encapsulated desktop browser that contains more HTML5 functionality, more RAM, more CPU processing power, and more file and network resources than your app will encounter on a real mobile device.

All of this means that the layout and behavior of your app in the Emulate tab is an approximation. CSS features and JavaScript APIs that are available in the Emulate tab are not necessarily available in real mobile device WebViews. To understand more about the difference between running your app in a WebView and running it in a browser, please see When is an HTML5 Web App a WebView App? It is impractical to simulate all the device quirks and API variations for all the mobile devices available in the world, thus the Emulate tab does not attempt to be a real device and rarely simulates the quirks associated with different device types. Ultimately, you must test your apps on real devices to confirm proper execution.

HINT: When using the Emulate tab, push the "bug" icon on the toolbar to open a Chrome DevTools console to debug your app while it runs in the Emulate tab browser. You might want to disable the auto-refresh feature, under the options icon on the toolbar (see image), to keep the Emulate tab browser from automatically restarting your app each time you save a file in your project.

While using the Emulate tab debug console you may see messages that are not part of your app. This is because the Emulate tab debug console is shared with the other node-webkit components that comprise the Intel XDK (the Intel XDK is also an HTML5 app). These extraneous console messages are most likely to appear when you switch focus to another tab in the Intel XDK while the Emulate tab debug console is open. Do not be alarmed by the appearance of these messages, they are not being generated by your application.

Keep in mind that there are some HTML5 APIs (JavaScript APIs, CSS rules and HTML tags) that will work in the Emulate tab but may not work on a real device (or may work differently or only on some real devices). This is because the underlying web runtime in the Emulate tab is based on the Chromium desktop browser. For example, many devices do not support WebRTC in their native WebView, but the Emulate tab will allow you to use that API. If you want to see specifically which version of Chromium is in use in the Emulate tab, type window.top.process.versions at the Emulate tab debug console to display an array of version numbers for many of the key elements used by the Intel XDK.

For detailed instructions see the Emulate Tab documentation.

Intel® App Preview provides you with a way to quickly preview your HTML5 web app on real devices, in the native WebView on that device. This native WebView is the HTML5 "runtime engine" in which your HTML5 code is interpreted; you can think of it as an embedded browser on your mobile device. See this blog post for an explanation of how running your web app in a native WebView differs from running your web app in a mobile browser.

App Preview can be used in conjunction with the Test tab or with the "Live Layout Editing" feature found on the Develop tab; both are described below in more detail. You can download and install App Preview onto any supported device, it does not require that your device be placed into a special "debug mode" or that it be "rooted" or "jail broken." Intel App Preview can be downloaded directly from the respective app stores for Android, iOS, Windows 8 and Windows Phone 8. Search for "Intel App Preview" in the app stores.

In essence, App Preview is a special Intel XDK packaged app that is missing the HTML5 parts of your project. You can think of it as an app that was built with an empty project. It works by copying your project files into this missing space and then executing them within the pre-built Cordova container. Thus, it provides a very accurate preview of how your app will look and behave when you build and install it on a real device.

There are a few limitations and points to be aware of when using App Preview:

• Third-party plugins are not supported, since they must be included at build time (due to the fact that plugins include native code, as well as the JavaScript API code).

• All of the "built-in" plugins (see the "Standard Cordova Plugins" and "Intel XDK Plugins" from the Plugins section of the Projects tab) are included in the pre-built App Preview container; so this is not an accurate representation of the memory requirements of your app.

• When used with the Test tab via the "Server Apps" or "Mobile" options, App Preview will mask those plugin APIs that you have not selected on the Plugins section of the Projects tab, in an attempt to provide a more accurate simulation of your application.

• When used with the Test tab via the "Local Apps" or "WiFi" options, App Preview will not mask plugin APIs (as described above). This means that APIs that you have not selected on the Projects tab will be visible to your application when it runs in App Preview.

• The specific plugin versions included in App Preview are fixed at release and cannot be changed during test. Thus, the versions of the plugins you specify on the Projects tab and build your app against may be different than those used when testing your app in App Preview.

Intel App Preview responds to two touch commands. A five-finger touch to any of App Preview's screens brings up version information for App Preview and its built-in plugins. A three-finger touch to the screen, while your app is running inside of App Preview, causes your app to exit and return to the main App Preview screen. The five-finger touch is also useful for getting a complete list of the plugins that are part of App Preview, this is helpful for understanding which plugin APIs will work when you test your app using App Preview.

Since App Preview is built for general-purpose use, it is not possible to include precisely the third-party plugins your app requires. Thus to test an app that requires third-party plugins you must use "feature detection" in your code to avoid calling those APIs that will be missing from App Preview. This means you should either write "fallback" code to get around APIs that will not be present, or simply avoid executing that code when you are testing in the App Preview container.

The Android version of App Preview is a WebView "debuggable" app, meaning that you can start a remote Chrome DevTools session with your app when it is running in App Preview while connected to your workstation via USB (see the Remote Chrome DevTools section, below, for more information). This feature is accessible from any workstation (Linux, Windows or OS X). When you use the Debug tab with an Android device you are actually running it inside of a Crosswalk WebView (via App Preview Crosswalk), not inside the "native" WebView on your Android device.

The iOS version of App Preview can be converted into a WebView "debuggable" app, so it can be used with the Debug tab and any host (Linux, Windows or OS X) or with Safari Remote Web Inspector(Develop > Device Name > index.html) from a Mac. Your iOS device must be attached to your workstation via USB. Converting App Preview into a debuggable app is needed for use with the Debug tab and is described in the relevant documentation pages.

For detailed instructions regarding the App Preview screens, see the App Preview documentation pages.

The Test tab provides a way to quickly preview your app, inside App Preview, and access to a simple JavaScript console for the webview in which your app is running. The Test tab's remote console does not accommodate JavaScript debugging or breakponts and has only limited CSS debug tools. It should only be used if you are unable to utilize the Debug tab or remote CDT.

The Test tab is essentially a weinre console (weinre stands for Web Inspector Remote) that operates in two "modes":

• remote console over the Internet (MOBILE toolbar option)
• remote console over your local network (WIFI toolbar option)

In order to access the weinre console you must insert the weinre script tag that is provided at the bottom of the Test tab into your index.html file. You may have to try a few different locations for the weinre script tag in your index.html before you find a location that works with the rest of your code and JavaScript libraries.

When operating "over the Internet" (MOBILE option) the weinre console connection between the Intel XDK and your device under test (the device running Intel App Preview) is facilitated via an Intel XDK cloud-based server. That means that both the Intel XDK and your test device must have Internet access and must be logged into your Intel XDK account.

When operating "over WiFi" (WIFI option) the weinre console connection between the Intel XDK and your device under test is direct to the Intel XDK running on your workstation. This means that the Intel XDK and your test device must reside on the same local network (i.e., they must be able to see each other on the same subnet). Your test devices and workstation do not need to be operating over WiFi to use this option. If your workstation is attached to a wired network, and that wired network and the WiFi interface on your test device are attached to the same local subnet, this connection will work.

In general, using the WIFI connection mode is fastest and preferred, since the network lags associated with real-time communication over the Internet can significantly affect the ability of the Intel XDK and the device under test to maintain a working weinre communication channel. Use the MOBILE option only as a backup; for example, if you are in an office environment where the device network and your workstation network are on different subnets; or, when your device network interface must use a mobile or cellular network (perhaps due to the type of testing you are performing).

One useful feature of the Test tab that is frequenly overlooked: you can "bake" the weinre script tag (from the Test tab) into an app that you build and install onto a device and then use the weinre console on the Test tab when that app starts running on your device. This is a useful way to debug apps that include third-party plugins or when you have no other option for debug or App Preview does not work for your situation. The restrictions above still apply, but this is a very useful twist on the Test tab that can help when you have no other options.

IMPORTANT! Always remember to remove the weinre script tag from your application's index.html file before you build a release version for publication to an app store!!

For detailed instructions regarding use of the Test tab, see the Test documentation pages.

UNDER CONSTRUCTION -- come back soon for more

For detailed instructions regarding use of the Debug tab, see the Debug documentation pages.

UNDER CONSTRUCTION -- come back soon for more

For detailed instructions regarding use of the Profile tab, see the Profile documentation pages.

UNDER CONSTRUCTION -- come back soon for more

For detailed instructions regarding use of the "Run My App" feature on the Develop tab, see the Live Development documentation pages.

UNDER CONSTRUCTION -- come back soon for more

For detailed instructions regarding use of the "Live Layout Editing" feature on the Develop tab, see the Live Development documentation pages.

UNDER CONSTRUCTION -- come back soon for more

For more details regarding the use of Chrome DevTools for remote debugging on Android devices, see this article titled Remote Debugging on Android with Chrome.

UNDER CONSTRUCTION -- come back soon for more

For more details regarding the use of Safari on Mac for remote debugging of iOS devices, see this Safari Web Inspector Guide document.

UNDER CONSTRUCTION -- come back soon for more

For more details regarding weinre for remote debugging remotely, see the weinre home page.