The Device Emulator GUI
How the Device Emulator Fits into the Intel XDK
Configure Emulator Environment
Test in Emulator
Debug and Edit
Next Step: Test on Actual Device(s)
Summary, Key Terms, and Resources
This page describes setting up and using the Intel® XDK device emulator. For an overview of the various Intel XDK test and debug capabilities, see the Test and Debug Overview.
The Device Emulator GUI
NOTE: Apps may run correctly in the emulator but encounter problems when run on an actual device. The processor on your host system is likely faster than the processor on an actual device, so performance-related problems are typically not seen in the emulator. Also, the up-to-date web run-time used by the device emulator may implement features of HTML5 more correctly than the web run-time on the actual device, especially if that device has an old OS version. Think of the devices inside the device emulator as a collection of "ideal" devices with nearly unlimited memory, processor, and HTML5 rendering features. Use the device emulator to quickly identify and fix many defects before you test your app on an actual mobile device. See Why Running in the Device Emulator Differs from Running on Actual Device(s).
After you choose your project in the Intel XDK PROJECTS tab, launch the device emulator by either:
- Clicking the EMULATE tab to display the Device Emulator as a docked window.
- In the DEVELOP tab Live Development Tasks pane, clicking Run My App > Run in Emulator to display the Device Emulator as a floating window.
A visual representation of the selected virtual device appears in the center of the EMULATE tab. To the right and left of the device being tested are two columns of palettes. Use the palettes to configure your test environment by choosing a device, settings, and so on (your screen may differ):
|To select a different tab, click its button. For example, after debugging issues, click the DEVELOP tab EDIT view to edit your source code.|
|The EMULATE tab toolbar appears on the top row. It provides easy access to frequently used buttons and controls, which are described below.|
|The palettes appear in two accordion-style columns, to the left and right of the virtual device. Use the palettes to choose the Device, Settings, and other features. As explained in Configure Emulator Environment below, you can: open (expand) and close each palette by clicking its name, move palettes between columns by dragging a palette, or show and hide an entire palette column by clicking the or button.|
|The virtual device under test appears in the center, based on the selected Device and its characteristics. You can use the slider in the toolbar to adjust the size of the virtual device.|
If you undock the EMULATE tab, you can move its undocked floating window to view it and the DEVELOP tab side-by-side. To undock this tab, click button near EMULATE and drag the undocked EMULATE window (as shown below). To return (dock) the floating window to the EMULATE tab, click the button or close the floating window.
The EMULATE Toolbar
The EMULATE tab toolbar appears on the top row:
|Click This||To Do This|
|| Reload the app for the device under test in the
EMULATE tab. This action reload your app's source files and restarts the app.
||Launches the built-in debugger in a floating window (described in Debug and Edit).|
|Display settings for this tab:
Use the When files change section to choose what the emulator should do after you modify your sources using the built-in editor and click the EMULATE tab. Choose one of the following:
Use Set background color to select a background color beneath the palettes and virtual device.
Use Configure emulation of unknown Cordova plugins to view and modify the plugin rules you set for this Intel XDK session. These rules are recorded as the emulator runs your app. When it encounters plugin calls for which it does not provide a native code replacement routine, it requests your decision on how it should continue for each unknown plugin, such as use the Fail callback, Success callback, or do not invoke either callback. For details about emulator handling of unknown plugins, see Unimplemented Cordova Plugin API Support in the Device Emulator.
Click again to close.
|Stop executing the app in the emulator. You might stop the app for various reasons, such as if an unimportant GUI event keeps occurring or excessive CPU time is used. To restart the app, you need to reload it, such as by clicking the button or save changes to your project files when the When files change setting allows reloading (see above).|
|Change (slide) the zoom percentage of the virtual device, and thus its size. Click the button to automatically zoom the virtual device to the maximum size that will fully fit in the window (its color turns blue if clicked); click it again to unselect the automatic zoom.|
|When present, indicates that an update package for the Intel XDK is available. Click to start the download process. When download completes, click to start the installation.|
|Provide links to display the: Help Page, Intel XDK Quick Tour, user forums, various documents, and Intel XDK About page (applies to all tabs).|
|Log in or view your Intel XDK account name (applies to all tabs). For example, the TEST and BUILD tabs
use your account. Once logged in, click once to display
your account name and the buttons below. Click
again to hide this information:
To log out, click .
To view/modify your account settings, click .
How the Device Emulator Fits into the Intel XDK
The Device Emulator Workflow
The recommended series of steps (workflow) to use the device emulator follows:
- Choose Project: Define the app to be tested in the Device Emulator by using the PROJECTS tab.
- Configure Emulator Environment: Choose a device and settings in the EMULATE tab.
- Test in Emulator: Test on-device sensors, and fire event using the EMULATE tab.
- Debug and Edit: Debug within the EMULATE tab and fix any problems found during testing by using the DEVELOP tab. You should retest fixes in the Device Emulator (EMULATE tab).
- Next Step: Test on Actual Devices: When you are satisfied with testing within the EMULATE tab, test mobile device(s) by using live development features in the DEVELOP tab or the TEST tab. You must first download and install the Intel App Preview tool on your mobile device.
The Device Emulator runs your application (app) in a simulated environment. You quickly see how your app looks and behaves on a variety of devices without having to acquire many test devices. For example, you can:
- Select a popular mobile device to determine the appearance of both the screen size and the resolution.
- See how well your app's responsive design can accommodate devices of different display sizes.
- Fire system events and control system parameters such as your location and test on-board devices.
You can debug your app using the Device Emulator's built-in debugger.
How the Device Emulator Fits into the Intel XDK
The top of the Intel XDK provides a row of tabs that describe the major steps of its workflow. To move to a new tab, simply click the tab's name (your screen may differ slightly):
For example, before you use the EMULATE tab with a new app, use the:
- PROJECTS tab to select the project and the file that starts your app (usually index.html). When creating a new project, specify an empty directory to contain project files and its project name.
- DEVELOP tab to modify your app's GUI design and edit its source code.
After you test your app using the EMULATE tab, use the DEVELOP tab again to fix source code issues found during testing. Return to the EMULATE tab to retest the fixed issues.
After you are satisfied with your app's behavior within the Device Emulator using a virtual device, use the DEVELOP tab live development features or the TEST tab to test the app and remotely debug it on real physical device(s). For example, you can enable live preview of your device (DEVELOP tab), use a USB cable to connect your device to your development system to enable remote debugging (Android* and Apple iOS* devices) or profiling (Android devices), test your app using a local device(s) either connected to your development computer by using to the same WiFi network or with a USB cable. Also, you can use your mobile device and Intel App Preview to test apps you have previously pushed to the Intel XDK servers from anywhere your device has an internet connection.For more information about the various Intel XDK tabs, see the Intel XDK Tabs Overview.
Choose a Project
Before you test an app using the EMULATE tab, you need to choose an existing choose your project or create a new project.
Use the PROJECTS tab to select the active project to be used by other tabs. Selecting the project will also select the index.html file within the chosen project for the Device Emulator. This tab also lets you remove the selected project from the project list.
- Open the Intel XDK.
- Click the down arrow to the right of the PROJECTS tab.
- Click the New Project button.
- Click the plus sign next to Samples and Demos. Several available demos are displayed in the General category. You might create sample or template project or open your own app project and use it while learning about the device emulator on this page.
- For instructions to import an HTML5 code base or select a sample or template, see Create, Import, and Manage Intel XDK Projects
Configure Emulator Environment
As shown in The Device Emulator GUI, the Device Emulator provides a series of palettes, each of which controls some aspect of the virtual environment. The palettes are divided into two accordion-style columns, one on the left and one on the right of the virtual device.Before you test your app in the EMULATE tab, set up each configuration that will be used to test your app. To test your app using multiple configurations, set up each configuration, test and debug it, edit your app, and repeat. Also, make sure the appropriate
<script ...lines are present.
Customizing the Device Emulator Appearance
- To undock the Emulator window, either click the button next to EMULATE, or in the DEVELOP tab, click Run My App > Run in Emulator. To return (dock) the floating window to the EMULATE tab, click the button or close the floating window.
- To open (expand) or close a palette, click its name. Expand a palette to view and modify its options.
- To hide or show a palette column, click the or button. For example, you might hide one column of palettes to increase the width available to display the virtual device under test.
- In the toolbar, use the slider or the button to make the virtual device larger or smaller.
- You can move palettes by dragging them to a different location.
Choose Device, Connection Type, and Other Characteristics
|Use This Palette||To Do This|
|Devices||Select a device (device under test), such as Apple iPhone 5* or whatever you prefer. The virtual device
chosen appears in the middle of the EMULATE tab, so you can view how your app fits on the device's screen and resolution.
You can choose the orientation as portrait or landscape using the buttons.
To simulate the user clicking the Back button on the chosen virtual device, click the button.
To maximize the width available to view the virtual device, use the Zooming percentage or hide palettes as described below in Configure Emulator Environment.To test your app using multiple devices, select each device, test and debug it, and repeat.
|Information||A summary of the currently selected settings appears, such as the selected Device, screen size and density, and other device details.|
|Choose Project Start File or URL||Allows you to specify an html page to help you test multi-page apps. The default start html page is
index.html in the project source directory.
To display an external web page in the emulator's virtual device, enter an absolute URL (with an
http:// or equivalent prefix). This is useful for testing web applications that rely on server-side support but want to be mobile-friendly. The
|Accelerometer||Open this palette and get familiar with its content.
Click the button to shake the image. On certain platforms, the shake may mean something different.Use this palette to simulate device rotation by dragging the small device using the mouse pointer. As you drag it, the accelerometer values change.
|AppMobi Live Update Service||Emulate updating your app's version. See the topic Test in Emulator.|
|Device & Network Settings||Open this palette and view the settings for the virtual device. Locate the
Connection Type drop-down. Specify the type of network connection you will use on your target mobile system in the
TEST tab. For example, if both your development system and the target device are on the same local wireless network, choose
Use this palette to choose:
Open this palette and get familiar with its content.
Use this palette to zoom the displayed map, simulate changes in the physical geographic location of the device by dragging the map or entering coordinates, choose a compass heading and type a speed, specify Global Positioning Satellite (GPS) delay time, simulate a GPS timeout, and use a recorded GPX file to simulate route movement.
Open this palette and get familiar with its content. Use this palette to simulate to fire system-level events:
In addition to the palettes, check the EMULATE tab settings by clicking the button in the toolbar.
Cross-platform Screen Resolution
Selecting a device in the Device Emulator determines the pixel dimensions of the frame where the app under test is rendered. You can view display details in the Information palette.
In addition to the screen size of the target device, consider the resolution or pixel density of the target device. Pixel density can be measured using pixels per inch (PPI).
Test in Emulator
After you have configured the Device Emulator environment, you can test the various features provided by your app's APIs, including on-board device sensors, app update, and firing events.
Please note that the Device Emulator provides its own implementation of the system code to simulate features of a real device. The Device Emulator is not an instruction-level emulator; it does not emulate an actual device or its processor, memory, operating system, and HTML5 rendering capabilities. For details, see: Why Running in the Device Emulator Differs from Running on Actual Device(s).
The Device Emulator supports the use of Apache Cordova* 3.x plug-in APIs. Use the Intel XDK Projects tab to specify which Cordova core and other third-party plug-ins your app will use.
NOTE: The Device Emulator assumes the entry point for the current project is index.html in the project source directory. The Device Emulator does not support use of mp3 and mp4 audio files.
If you recently modified your sources using the DEVELOP tab, click the button to update the virtual device shown in the EMULATE tab. The first time you do this, consider choosing the option to have the app's modified files automatically reload when you click EMULATE. At any time, you can view or change the auto- or manual-load settings by clicking the button on the left side of the toolbar.
If your app uses the Apache Cordova APIs, the config.xml or intelxdk.config.xml file provides a helpful list of the on-board sensors your app uses; this list may be helpful during testing.
Scrolling in the Device Emulator
If you open enough palettes (or choose a large enough device in the Device palette) the Device Emulator UI may become larger than your Intel XDK window. In that case the entire Device Emulator window becomes scrollable. You can scroll using the mouse wheel or the arrow keys. There is also a vertical scrollbar on the right side.
If the app emulated by the virtual device displays a UI that is larger than the Intel XDK window, then the window in the virtual device also becomes scrollable. To scroll within the device window:
- Click the device window to give it focus.
- To scroll vertically, either use the mouse wheel or the up arrow or down arrow keys.
- To scroll horizontally, use the left arrow or right arrow keys.
If your host computer has a touch screen, you can also use touch-based scrolling, both for the device window and the entire Device Emulator UI.
Use this palette to simulate device rotation and gyroscopic movement by dragging the small device using the mouse pointer. As you drag it, the displayed accelerometer values change:
- Rotation on the x-, y-, and z-axis.
- Gyroscopic values alpha, beta, and gamma.
Apps that use accelerometer APIs can show the changes to the accelerometer values visually, such as the Hello Cordova demo. To choose this project, open the Projects tab and click: Start a New Project > Samples and Demos > select HTML5+Cordova > Hello Cordova. You can view his sample's documentation, including related emulator and debugging information.
Use this palette to simulate your app's geographical location capabilities. This palette provides a geo location map, a slider to zoom in or out, and other capabilities.
Test Live Update
You can test you app's ability to send an Update notification to users that a new version of your app is available. You can choose to emulate the Live Update now, after a reboot occurs, or to notify the user or app. To do this:
- Open the AppMobi Live Update Service palette.
- Select how the test message will be delivered. Messages can be delivered automatically or by notifying the user of the app that a message needs to be viewed (see the appMobi service documentation).
- Type a message to be entered into a change log.
- Click Send.
Debug and Edit
To modify your source code at any time, click the DEVELOP tab and click the file name in the sidebar to select the file to be edited, such as index.html.
Debugging Inside the Device Emulator
The device emulator - like the rest of the Intel XDK - is an HTML5 application that runs inside node-WebKit. Node-WebKit uses a web runtime (WebKit) based on the web runtime used in the standard Chrome browser. Your app runs within an inner HTML frame whose size depends on the currently selected device.
Node WebKit provides a built-in debugger, which is based on and resembles the standard Chrome Developer Tools (CDT) debugger. You can use the built-in debugger to debug your application. The EMULATE tab simulates device viewport sizes, touch events, user agent strings, and various device APIs (other than unimplemented APIs listed below) for a convenient debugging experience using standard Chrome Dev Tools. (Actually you are debugging the entire Intel XDK, but the built-in debugger hides the parts outside of the inner frame containing your app.)
To start the debugger, click the button in the toolbar. The debugger appears in a floating window, as shown in the lower part of the screen below (your screen may differ):
To close the debugger, click the red x in the upper-right corner.
This debugger lets you view elements and resources, type commands into a console, and perform other functions. For example, display Elements and right click to select options for that source line from a context menu (as shown). For information about this debugger, see https://developers.google.com/web/tools/chrome-devtools/debug.
Use the debugger to focus on the emulated app's elements and sources. If you see Console messages from files that are not part of your app's sources, these messages may be from the Intel XDK and can be ignored.
The debugger lets you view your source code. If you modify the source code in the debugger, this will impact the future behavior of the EMULATE tab as you continue testing your app. However, modifying sources in the debugger does not modify your actual source code in the DEVELOP tab.
The EMULATE tab simulates a subset of the device APIs that are available to your application. The only way to debug these non-simulated APIs is by using on-device debugging with App Preview or a built application.
For a list of unimplemented APIs in the Device Emulator (and other limitations), see this page: Why Running in the Device Emulator Differs from Running on Actual Device(s).
Editing Your Source Files
The debugger lets you view and modify the source code in the debugger, but changes you make in the debugger will not modify your actual source code. Either use your favorite external editor or the code editor built into the DEVELOP tab to modify your sources:
- After you open or create a project, click the DEVELOP tab. If needed, click the CODE button to display the code editor view.
- In the left sidebar under the project name is a list of source files (file tree). Click the source file to be modified. The selected file appears.
- In the left sidebar, after you modify a file, a Working Files section appears above the project name. To add a file immediately to the Working Files section, double-click its name.
- Modify the file(s) as needed. To save your changes for this file, either click the File > Save menu item or press Ctrl+S or Cmd+S.
- For more information about the built-in editor, see Using the Built-in Code Editor.
To return to the EMULATE tab, click EMULATE. To restart your app so its appearance and behavior in the EMULATE tab is consistent with your saved sources, click the button. If you use an external editor, remember to click the button after you save the file.
The DEVELOP tab also has an APP DESIGNER view for the App Designer GUI layout editor. Click the DESIGN button to use this GUI view for projects created to use App Designer.
For more information about the various Intel XDK tabs, see the Intel XDK Tabs Overview topic.
Retest Your App
After you have fixed any issues using the DEVELOP tab, retest the modified parts of your app using the applicable devices and settings in the EMULATE tab. Return briefly to the topic Test in Emulator.
Next Step: Test on Actual Device(s)
After you complete testing using the device emulator and are satisfied with your app's quality, the next step is to test the app using the actual device(s) it will support. Before you push your app to the server, log into your Intel XDK account.For each mobile device:
- Download the Intel App Preview app from the appropriate app store(s) and install it on your Android, Apple iOS, or Microsoft Windows Phone 8* mobile devices, or your Windows 8 tablet or laptop.
- To preview your running app during development, in the DEVELOP tab Code view, use the Live Development Tasks. This lets you run and view your app on a device connected to your development computer using WiFi or USB cable, or preview the app in a browser window. Alternatively, you can use the TEST tab after you sync your app with the testing server.
- To access your app built previously, launch the Intel App Preview app and log into your Intel XDK account.
In the DEVELOP or TEST tab, you can learn more by clicking the button in upper-right corner. For a video about using the TEST tab, view this video:
Additional ways of testing include:
- On Android and iOS devices, use the DEBUG tab to access the app running remotely on the target device connected with a USB cable. See the instructions on that tab.
- Use a remote debugger (such as weinre) that accesses the app running on the target device. See the instructions on the TEST tab.
- Use the simulator or emulator provided with each respective SDK. You use the SDK simulator or emulator on your development system, without access to a real device.
Summary, Key Terms, and Resources
This page described how to use the Device Emulator, part of the Intel XDK, to test and debug an app.
|Choose Project||You created a project using a demo app in the PROJECTS tab.|
|Configure Emulator Environment||The Devices palette lets you choose the virtual device to be viewed. You need to check the Network & Device Settings before you use the Device Emulator.|
|Test in Emulator||You tested the app's APIs by clicking its buttons and the app's display characteristics in the EMULATE tab. You also learned about using the built-in debugger.|
|Debug and Edit||You modified the source code and saved the file in the DEVELOP tab, code editor view. You then retested the changes in the EMULATE tab.|
|Next Step: Test on Actual Device(s)||You learned that the next steps are to test the app on real physical devices using the TEST tab.|
- mobile app: An app that executes on a target device. It executes in the device's WebView and interacts with the user and on-board device sensors.
- on-board sensor: Built-in sensors available on the real device, such as its accelerometer, geo location, and similar features.
- real device: Actual physical hardware, such as a smart phone, tablet, or other mobile device.
- virtual device: Software environment that simulates a real device. It is convenient for testing how an app will look and function on actual, physical hardware.
- web app: An app that executes on a web server. To use this type of app, a mobile device uses a web browser and internet access.
- The main Intel XDK page at: http://xdk.intel.com/
- The Intel XDK introduction page at:Introduction to the Intel XDK
- To quickly walk through the Intel XDK development workflow while using a demo sample: Getting Started Tutorial .
- Device emulator limitations at: Why Running in the Device Emulator Differs from Running on Actual Device(s)
- For a description of when to use the various Intel XDK and related debug and test options, see Debug and Test Overview.