microsoft/cordova-simulate

microsoft/cordova-simulate

Description: Simulates your Apache Cordova application in the browser.

Language: HTML

License: NOASSERTION

Stars: 220

Forks: 57

Open issues: 6

Created: 2015-10-03T21:17:05Z

Pushed: 2026-06-24T02:53:13Z

Default branch: master

Fork: no

Archived: no

README:

Cordova-Simulate 

Simulates your Apache Cordova application in the browser.

Table of Contents

• [Installation](#installation)
• [Usage](#usage)
• [CLI](#cli)
• [API](#api)
• [What it does](#what-it-does)
• [Features](#features)
• [Supported plugins](#supported-plugins)
• [Simulate in Docker container](#simulate-in-docker-container)
• [Adding simulation support to plugins](#adding-simulation-support-to-plugins)
• [Detailed steps](#detailed-steps)
• [Simulation Host Files](#simulation-host-files)
• [App Host Files](#app-host-files)
• [The "messages" Object](#the-messages-object)

Installation

npm install -g cordova-simulate

Usage

CLI

From the command line anywhere within a Cordova project, enter the following:

simulate [] [--device=] [--corsproxy=] [--dir=] [--livereload=] [--port=] [--forceprepare=] [--simhostui=] [--simulationpath=] [--target=] [--lang=] [--theme=] [--middleware=] [--generateids=] [--spaurlrewrites=] [--showbrowser=] [--chromiumpath=]

See parameters description in the [API](#api) section.

API

Use require('cordova-simulate') to launch a simulation via the API:

var simulate = require('cordova-simulate');
simulate(opts);

Where opts is an object with the following properties (all optional):

• platform - any Cordova platform that has been added to your project. Defaults to browser.
• device - specify the id of a device to start with instead of a platform (the platform will be determined by the

device). Supported android devices are Nexus4, Nexus6, Nexus7, Nexus10, OptimusL70, G5, GalaxyNote7 and GalaxyS5. Supported ios devices are iPhone4, iPhone5, iPhone6, iPhone6Plus, iPad and iPadPro. Supported windows devices are Lumia930, Lumia950 and SurfacePro. Supported generic devices (which will use the browser platform) are Generic320x480, Generic320x568, Generic360x640, Generic384x640, Generic412x732, Generic768x1024, Generic800x1280 and Generic1920x1080.

• target - the name of the browser to launch your app in. Can be any of the following: default, chrome, edge, firefox, opera, safari, chromium.
• port - the desired port for the server to use. Defaults to 8000.
• lang - the language to display in the interface (does not impact console output). Supported values (case-insensitive)

are cs (Czech), de (German), es (Spanish), fr (French), it (Italian), ja (Japanese), ko (Korean), pl (Polish), pt (Portuguese), ru (Russian), tr (Turkish), zh-Hans (Simplified Chinese) and zh-Hant (Traditional Chinese). Additional tags are ignored (for example, de-DE is treated as de).

• dir - the directory to launch from (where it should look for a Cordova project). Defaults to cwd.
• simhostui - the directory containing the UI specific files of the simulation host. Defaults to the bundled simulation host files, found in src/sim-host/ui.
• livereload - a boolean. Set to false to disable live reload. Defaults to true.
• forceprepare - a boolean. Set to true to force a cordova prepare whenever a file changes during live reload. If this is false, the server will simply copy the changed file to the platform rather than doing a cordova prepare. Ignored if live reload is disabled. Defaults to false.
• corsproxy - boolean indicating if XMLHttpRequest is proxied through the simulate server. This is useful for working around CORS issues at development time. Defaults to true.
• touchevents - a boolean. Set to false to disable the simulation of touch events in App-Host. Defaults to true.
• simulationpath - the directory where temporary simulation files are hosted. Defaults to projectRoot/simulate.
• simhosttitle - specifies the title of the simulation window. Defaults to Plugin Simulation.
• middleware - a path that points to express middleware. This can be used to write custom plugins that require the full power of NodeJS.
• generateids - a boolean that generates unique ids for simulated devices at startup. Defaults to false.
• livereloaddelay - the delay in milliseconds between saving of a modified file and the application page reloading. You can try to increase the delay in case the simulator server crashes while frequent page reloading. Defaults to 200ms.
• spaurlrewrites - a boolean. Set to true to fix page refreshing in case the default application URL (/index.html) in the browser was changed by the router in single page applications. Defaults to false.
• showbrowser - a boolean. Set to true to launch browsers when simulation starts. Defaults to true.
• chromiumpath - a path that points to Chromium executable file. Required when using Chromium as target on win32.

Use launchBrowser to open target browser with specific url:

require('cordova-simulate').launchBrowser(target, url);

• target - which browser you want to open, like Chrome, Edge, Firefox, Opera, Safari, Chromium.
• url - specific website url you want to load.

What it does

Calling simulate() will launch your app in the browser, and open a second browser window displaying UI (the simulation host) that allows you to configure how plugins in your app respond.

Features

• Allows the user to configure plugin simulation through a UI.
• Launches the application in a separate browser window so that it's not launched within an iFrame, to ease up debugging.
• Allows user to persist the settings for a plug-in response.
• Allows plugins to customize their own UI.
• Reloads the simulated app as the user makes changes to source files.

> Note for live reload: Changes to files such as images, stylesheets and other resources are propagated to the running app without a full page reload. Other changes, such as those to scripts and HTML...