Start a Firefox OS simulator
Switch branches/tags
Clone or download
Permalink
Failed to load latest commit information.
examples
tests/unit
.editorconfig
.gitignore
.travis.yml
LICENSE
README.md
gulpfile.js
index.js
package.json

README.md

node-firefox-start-simulator Build Status

Start a Firefox OS simulator.

Install with NPM

This is part of the node-firefox project.

Installation

From git

git clone https://github.com/mozilla/node-firefox-start-simulator.git
cd node-firefox-start-simulator
npm install

If you want to update later on:

cd node-firefox-start-simulator
git pull origin master
npm install

npm

npm install node-firefox-start-simulator

Usage

var startSimulator = require('node-firefox-start-simulator');

// `startSimulator` returns a Promise
startSimulator(options).then(function(simulator) {

});

where options is a plain Object with any of the following:

  • detached: start the simulator as a detached process. If our script is killed, the simulator will still be running.
  • port: make the simulator listen to this port for debugging. If not specified, we'll find an available port.
  • version: start a simulator in this version. If not specified, we'll start the first simulator that we can find.
  • verbose: pipe the output from the simulator to standard I/O. For example, you'll get JavaScript console.log messages executed in the simulator.

and simulator is an object containing:

  • binary: path to the simulator binary
  • bin: an alias to binary
  • profile: path to the simulator profile
  • pid: process id
  • process: the actual process object
  • port: the port where the simulator is listening for debugging connections

There is also a startSimulator.all() utility to launch many simulators at once:

startSimulator.all(options)(simulatorOptions)
  .then(function(launchedSimulators) {
    // launchedSimulators is a list of simulator objects
  });

The options parameter here is the same as above - these options will be commonly applied to all the simulators launched.

The call to startSimulator.all() returns a function that takes a list of simulators and returns a Promise to launch them all. The result of that Promise is launchedSimulators, a list of all the simulators that were launched.

Note: This function returning a function may seem like a roundabout way to do things, but take a look at the examples below to see how this works with findSimulators() and other Promise-based APIs.

Examples

Start any simulator on the first available port

var startSimulator = require('node-firefox-start-simulator');

startSimulator().then(function(simulator) {
  console.log('Started simulator at port', simulator.port);
}, function(err) {
  console.log('Error starting a simulator', err);
});

Start all simulators found on your system

var findSimulators = require('node-firefox-find-simulators');
var startSimulator = require('node-firefox-start-simulator');

// startSimulator.all() returns a function that applies the common options to
// all the simulators discovered by findSimulators()

findSimulators.then(startSimulator.all({ detached: true }));

Have a look at the examples folder for more!

Documentation

If you want to contribute to this module, it might be interesting to have a look at the way WebIDE launches the simulator. The code for this is in simulator-process.js. Whenever possible, we want to mimic the WebIDE experience as closely as possible.

History

This is based on initial work on fxos-start by Nicola Greco.