Debug and Test Overview

This article will provide you with a high-level overview 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 details (and are referenced from this page).

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

To help you decide on the optimum debug solution, see this imperfectly prioritized list. Note that some of the options in this list may not make sense until you read the rest of this document.

If you are debugging on Android, use:

  • The Simulate tab for basic JavaScript logic and approximate layout (limited third-party plugin support).
  • A debuggable build with remote CDT for very accurate behavior (esp. with third-party plugins).
  • Using weinre with a built app (esp. with third-party plugins).

If you are debugging on iOS, use:

  • The Simulate tab for basic JavaScript logic and approximate layout (limited third-party support).
  • Web Inspector Remote with a Mac for very accurate behavior (esp. with third-party plugins).
  • Using weinre with a built app (esp. with third-party plugins).

If debugging on Windows or Windows Phone, use:

  • The Simulate tab for basic JavaScript logic and approximate layout.
  • Using weinre with a built app (esp. with third-party plugins).

In addition to the debug methods recommended above (and in the table below), your desktop browser can be a very helpful tool in locating basic HTML5 app issues. Simply open your index.html file directly with your desktop browser. Using this approach will not work with calls to Cordova APIs, but it can provide insight into issues that other methods cannot or may not reveal.

Use this table to further refine the optimum debug solution for your situation:

  Simulate Tab Remote CDT Web Inspector Remote weinre
My app includes 3rd-party plugins   Android iOS Android, iOS, Windows
I need to debug JavaScript source X X X  
I need a JavaScript console X X X X
I need to inspect HTML elements X X X X
I need to debug CSS interactively X X X X
I need to identify JavaScript performance “hot spots”   X X  
I need to quickly review changes to my source files X      

Intel XDK Simulate Tab

The Simulate tab is an implementation of the open-source Cordova Simulate project and is best used for quick preview and debug of your application. 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.

You should view the Simulate tab as a Cordova API simulator. It provides you with a convenient viewport to quickly visualize the approximate layout of your app on various devices and it simulates the core Cordova APIs, making it easier to debug apps that use those APIs. It does not simulate real devices nor does it simulate third-party Cordova plugin APIs. Getting your app to work in the Simulate tab is no guarantee that it will work on a real device. Conversely, if things work on a real device but do not work in the Simulate tab, that is not an indication that your app is "broken." The only way to know, with certainty, that your app works as intended is to build it and install it on real devices. You must use a real device to confirm proper operation of device-specific code and third-party plugins and to confirm your application layout!

The Simulate tab includes a toolbar to control the simulation (start, stop, restart, etc.) and a convenient collection of device viewports for previewing your app's layout. It simulates some common mobile device events and provides a userAgent string for the selected device. The simulator runs within the context of the Node-WebKit runtime and contains more HTML5 functionality than the WebView that is on a real mobile device. It has full access to your development machine's resources; meaning the available RAM, CPU process power and file and network resources are much different in the Simulate tab than what your app will find on a real mobile device.

The layout and behavior of your app in the Simulate tab is an approximation. CSS features and JavaScript APIs that are available in the Simulate tab are not guaranteed to be available on a real device. To understand more about the difference between running your app on a device 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 Simulate 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 Simulate tab, push the "bug" icon on the toolbar to open a Chrome DevTools console to debug your app while it runs in the Simulate tab browser window. If you are making frequent changes to your project files while using the simulator, disable the auto-refresh feature to prevent the simulator from automatically restarting your app with each file save.

Keep in mind that there are some HTML5 APIs (JavaScript APIs, CSS rules and HTML tags) that will work in the simulator but may not work on a real device (or may work differently on a real device). This is because the underlying web runtime used by the simulator is based on Node-WebKit. For example, many devices do not support WebRTC in their native WebView, but the Simulate tab does work with that API.

For detailed instructions see the Simulate tab documentation. For a list of the Simulate tab's limitations, please read the Device Simulator Limitations doc page.

Intel® App Preview

NOTE: As of August 16, 2017, Intel App Preview has been retired and is no longer available in the respective mobile app stores; if you already have a copy of Intel App Preview on your test device it will continue to work, but you can no longer download it from a mobile store for new installations.

Remote Chrome* DevTools* (Remote CDT)

Using the Google* Chrome browser on your workstation, in conjunction with "remote CDT," is a very powerful debugging environment. In this environment you are able to debug a built app as it runs directly on your device. You have nearly 100% of the functionality of Chrome DevTools available to you, as if you were debugging a browser app on your workstation. This scenario works for the following three situations:

  • A built app installed on a USB-connected Android 4.4+ device, with developer options enabled.

  • A Crosswalk for Android app installed on a USB-connected Android 4.1+ device, with developer options enabled.

  • Running your app in Intel App Preview for Android on a USB-connected Android 4.4+ device, with developer options enabled.

Before you attempt to use this debug technique, you must:

Additional details regarding how to configure your system to use remote Chrome DevTools to debug your Android app are available in the online Intel XDK documentation.

Web Inspector* Remote

If you own a Mac and an Apple developer account, you can utilize Web Inspector in Safari to remotely debug an iOS Cordova app in a way that is analogous to using Remote Chrome DevTools with an Android Cordova app. See Using Web Inspector Remote to Debug iOS* Cordova Apps for details.

Using Node weinre* to Debug Your App

For those situations where you cannot utilize remote debug over USB, weinre is a useful alternate solution. This solution can be used with a built app or with an app that is running with App Preview. This solution does not accommodate JavaScript debugging or breakpoints and has only limited CSS debug tools.

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:

For full details on using this technique, see the doc page titled Using Node weinre to Debug Cordova* Apps.

Intel XDK Test Tab [RETIRED]

NOTE: As of August 16, 2017, Intel App Preview has been retired and is no longer available in the respective mobile app stores; if you already have a copy of Intel App Preview on your test device it will continue to work, but you can no longer download it from a mobile store for new installations.

The Test tab provides a way to quickly preview your app, inside the Intel App Preview application.

The weinre console feature of the Test tab has been retired. Please refer to the weinre section of this document for an alternate open-source solution.

When operating "over WiFi" (the WIFI option) the 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 part of the same subnet, this connection will work.

In general, using the WIFI connection mode of the Test tab is the fastest and preferred operation mode, since the network delays 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 communication channel. Use the MOBILE option 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 tests you are performing).

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

Intel XDK Debug Tab [RETIRED]

NOTE: As of December 12, 2016, the Intel® XDK Debug tab has been retired. You can no longer build debug modules with any version of the Intel XDK. Your project will continue to be recognized as an Intel XDK HTML5 mobile app project and will continue to build (using the Build tab), but the ability to build debug modules has been removed from the Intel XDK.

As an alternative, we recommend that you use the Simulate tab for basic debugging. You can debug a built Android app directly on-device, with full JavaScript and CSS debugging, by way of remote Chrome* DevTools*. For those who have access to a Mac, you can use remote web inspector with Safari to debug your built iOS apps. In addition, you can use weinre by installing a weinre server directly on your development system.

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