Using Firefox OS Simulator

This article is in need of a technical review.

This page describes the Firefox OS Simulator for developers targeting Firefox OS 1.2 or later. If you're developing apps for Firefox OS 1.1, then you should check out the documentation for the Firefox OS 1.1 Simulator instead.

The Firefox OS Simulator is a version of the higher layers of Firefox OS that simulates a Firefox OS device, but runs on the desktop. This means that in many cases, you don't need a real device to test and debug your app. It runs in a window the same size as a Firefox OS device, includes the Firefox OS user interface and built-in apps, and simulates many of the Firefox OS device APIs.

The Simulator is packaged and distributed as a Firefox add-on. Once you've downloaded it and installed it in Firefox, you can run it, push apps to it, and attach the developer tools to it, using the App Manager.

Installation

To install the simulator, click the button below. Multiple versions are available, and you are advised to install them all, for maximum flexibility):

Install Simulator

To start the Simulator, see the instructions in the App Manager documentation. Once the Simulator's running you can push apps to it and debug them using the App Manager, just as you can with a real device.

Note: The Simulator (v 1.2 and 1.3) currently reports an incorrect Gecko user agent string: see bug 964598 for more details.

The Simulator UI

The Simulator appears as a separate window, sized so the simulated screen area is 320x480 pixels. To simulate touch events you can click the mouse button and drag while holding the button down. So by clicking and dragging right-to-left from the Home Screen, you'll see the built-in apps, as well as any apps you have added:

The Simulator has two buttons in a toolbar at the bottom:

  • the button on the left takes you to the Home screen, or switches the Simulator off if you hold it down
  • the button on the right switches the Simulator between portrait and landscape orientation. This will generate the orientationchange event.

Limitations of the Simulator

Note that the Firefox OS Simulator isn't a perfect simulation.

Hardware limitations

Apart from screen size, the Simulator does not simulate the hardware limitations of a Firefox OS device such as available memory or CPU speed.

Audio/video codecs

The following codecs depend on hardware-accelerated decoding and are therefore not yet supported:

  • MP3
  • AAC
  • H.264 (MP4)
  • WebM

This means it isn't possible to use the Simulator to test video playback in apps and on websites like Youtube that rely on these codecs.

Unsupported APIs

Certain APIs that work on the device won't work on the Simulator, generally because the supporting hardware is not available on the desktop. We've implemented simulations for some APIs such as geolocation, and expect to add more in future releases. However, at the moment the following APIs are not supported. Using them might throw errors or just return incorrect results:

Getting help

If you have a question, try asking us on the dev-developer-tools mailing list or on #devtools on irc.mozilla.org.

How to enable verbose logging

You can see messages logged from your app in the Web Console, which you can attach to your app using the App Manager. If you want to catch early messages happening during app startup, before the console gets connected and working, you can enable verbose logging in the Simulator.

Visit about:config and create a new preference. The preference name is different for each version of the Simulator:

  • extensions.fxos_1_3_simulator@mozilla.org.sdk.console.logLevel for Firefox OS 1.3
  • extensions.fxos_1_2_simulator@mozilla.org.sdk.console.logLevel for Firefox OS 1.2

Set it to the string value "all", and disable, then reenable, the add-on in the Add-on Manager. Now extra messages about the Simulator's operation will appear in the Browser Console.

Document Tags and Contributors

Last updated by: wbamberg,