Simulates your Apache Cordova application in the browser.
npm install -g cordova-simulate
From the command line anywhere within a Cordova project, enter the following:
simulate [<platform>] [--device=<DEVICE_ID>] [--corsproxy=<true|false>] [--dir=<DIR>] [--livereload=<true|false>] [--port=<PORT>] [--forceprepare=<true|false>] [--simhostui=<SIM_HOST_UI_MODULE_PATH>] [--simulationpath=<SIMULATION_PATH>] [--target=<BROWSER>] [--lang=<LANG>] [--theme=<THEME>] [--middleware=<MIDDLEWARE_PATH>] [--generateids=<true|false>] [--spaurlrewrites=<true|false>] [--showbrowser=<true|false>] [--chromiumpath=<CHROMIUM_PATH>]
See parameters description in the API section.
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
androiddevices areNexus4,Nexus6,Nexus7,Nexus10,OptimusL70,G5,GalaxyNote7andGalaxyS5. Supportediosdevices areiPhone4,iPhone5,iPhone6,iPhone6Plus,iPadandiPadPro. Supportedwindowsdevices areLumia930,Lumia950andSurfacePro. Supported generic devices (which will use thebrowserplatform) areGeneric320x480,Generic320x568,Generic360x640,Generic384x640,Generic412x732,Generic768x1024,Generic800x1280andGeneric1920x1080. - 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) andzh-Hant(Traditional Chinese). Additional tags are ignored (for example,de-DEis treated asde). - 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
falseto disable live reload. Defaults totrue. - forceprepare - a boolean. Set to
trueto force acordova preparewhenever a file changes during live reload. If this isfalse, the server will simply copy the changed file to the platform rather than doing acordova prepare. Ignored if live reload is disabled. Defaults tofalse. - 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
falseto disable the simulation of touch events in App-Host. Defaults totrue. - 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
trueto fix page refreshing in case the default application URL (/index.html) in the browser was changed by the router in single page applications. Defaults tofalse. - showbrowser - a boolean. Set to
trueto launch browsers when simulation starts. Defaults totrue. - chromiumpath - a path that points to Chromium executable file. Required when using Chromium as
targetonwin32.
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.
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.
- 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 files, trigger a full page reload.
This preview version currently includes built-in support for the following Cordova plugins, some of them are deprecated that not being maintained and updated by official:
- cordova-plugin-battery-status
- cordova-plugin-camera
- cordova-plugin-console(deprecated)
- cordova-plugin-contacts(deprecated)
- cordova-plugin-device
- cordova-plugin-device-motion
- cordova-plugin-device-orientation
- cordova-plugin-dialogs
- cordova-plugin-file
- cordova-plugin-geolocation
- cordova-plugin-globalization(deprecated)
- cordova-plugin-inappbrowser
- cordova-plugin-media
- cordova-plugin-network-information
- cordova-plugin-statusbar
- cordova-plugin-vibration
Cordova-simulate support cordova application simulation in Docker container, here is the example as below:
-
Follow the VS Code official documentation to setup your environment and install related extensions(Remote Development is recommended) to use a remote development approach.
-
In the local react-native project, add
Dev Containerconfigure folder and files:.devcontainer -devcontainer.json -Dockerfile -
Сreate Dockerfile extending your image. For example you can use the following Dockerfile:
FROM mcr.microsoft.com/devcontainers/base:jammy RUN npm install -g cordova cordova-simulate -
Configure your
devcontainer.jsonfile as needed. Below is a sample configuration:{ "name": "Cordova Container", // Sets the run context to one level up instead of the .devcontainer folder. "context": "..", // Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename. "dockerFile": "Dockerfile", } -
Open Command Palette and run the following command
Dev Containers: Open Folder in Containerto reopen your project in a container -
Install supported browser in container and execute
simulate.
It also allows for plugins to define their own UI. To add simulation support to a plugin, follow these steps:
- Clone this repository (
git clone https://github.com/microsoft/cordova-simulate.git), as it contains useful example code (seesrc/plugins). - Add your plugin UI code to your plugin in
src/simulation. Follow the file naming conventions seen in the built-in plugins.
In your plugin project, add a simulation folder under src, then add any of the following files:
sim-host-panels.html
sim-host-dialogs.html
sim-host.js
sim-host-handlers.js
app-host.js
app-host-handlers.js
app-host-clobbers.js
sim-host-panels.html
This defines panels that will appear in the simulation host UI. At the top level, it should contain one or more
cordova-panel elements. The cordova-panel element should have an id which is unique to the plugin (so the plugin
name is one possibility, or the shortened version for common plugins (like just camera instead of
cordova-plugin-camera). It should also have a caption attribute which defines the caption of the panel.
The contents of the cordova-panel element can be regular HTML, or the various custom elements which are supported
(see the existing plugin files for more details).
This file shouldn't contain any JavaScript (including inline event handlers), nor should it link any JavaScript files.
Any JavaScript required can be provided in the standard JavaScript files described below, or in additional JavaScript
files that can be included using require().
sim-host-dialogs.html
This defines any dialogs that will be used (dialogs are simple modal popups - such as used for the Camera plugin). At
the top level it should contain one or more cordova-dialog elements. Each of these must have id and caption
attributes (as for sim-host-panels.html). The id will be used in calls to dialog.showDialog() and
dialog.hideDialog() (see cordova-simulate/src/plugins/cordova-plugin-camera/sim-host.js
for example code).
Other rules for this file are the same as for sim-host-panels.html.
sim-host.js
This file should contain code to initialize your UI. For example - attach event handlers, populate lists etc. It should
set module.exports to one of the following:
- An object with an
initializemethod, like this:
module.exports = {
initialize: function () {
// Your initialization code here.
}
};- A function that returns an object with an
initializemethod. This function will be passed a single parameter -messages- which is a plugin messaging object that can be used to communicate betweensim-hostandapp-host. This form is used when the plugin requires thatmessagesobject - otherwise the simple form can be used. For example:
module.exports = function (messages) {
return {
initialize: function () {
// Your initialization code here.
}
};
};In both cases, the code currently executes in the context of the overall simulation host HTML document. You can use
getElementById() or querySelector() etc to reference elements in your panel to attach events etc. In the future,
this will change and there will be a well defined, limited, asynchronous API for manipulating elements in your
simulation UI.
sim-host-handlers.js
This file defines handlers for plugin exec calls. It should return an object in the following form:
{
service1: {
action1: function (success, error, args) {
// exec handler
},
action2: function (success, error, args) {
// exec handler
}
},
service2: {
action1: function (success, error, args) {
// exec handler
},
action2: function (success, error, args) {
// exec handler
}
}
}It can define handlers for any number of service/action combinations. As for sim-host.js, it can return the object
either by;
- Setting module.exports to this object.
- Setting module.exports to a function that returns this object (in which case the messages parameter will be passed to that function).
app-host.js
This file is injected into the app itself (as part of a single, combined, app-host.js file). Typically, it would
contain code to respond to messages from sim-host code, and as such module.exports should be set a function that
takes a single messages parameter. It doesn't need to return anything.
app-host-handlers.js
This file is to provide app-host side handling of exec calls (if an exec call is handled on the app-host side,
then it doesn't need to be handled on the sim-host side, and in fact any sim-host handler will be ignored). The
format is the same as sim-host-handlers.js.
app-host-clobbers.js
This file provides support for "clobbering" built in JavaScript objects. It's form is similar to app-host-handlers.js,
expect that the returned object defines what you are clobbering. For example, the built-in support for the geolocation
plugin uses this to support simulating geolocation even when the plugin isn't present in the app (just like Ripple
does), by returning the following:
{
navigator: {
geolocation: {
getCurrentPosition: function (successCallback, errorCallback, options) {
// Blah blah blah
},
watchPosition: function (successCallback, errorCallback, options) {
// Blah blah blah
}
}
}
}A messages object is provided to all standard JavaScript files on both the app-host and sim-host side of things.
It provides the following methods:
messages.call(method, param1, param2 ...): Calls a method implemented on "the other side" (that were registered by
calling messages.register()) and returns a promise for the return value, that is fulfilled when the method returns.
messages.register(method, handler): Registers a method handler, which can be called via messages.call().
messages.emit(message, data): Emits a message with data (scalar value or JavaScript object) which will be received by
any code that registers for it (in both app-host and sim-host).
messages.on(message, handler): Register interest in a particular message.
messages.off(message, handler): Un-register interest in a particular message.
Note that:
- All the above methods are isolated to the plugin - that is, they can only be used to communicate within the plugin's own code. For example, when you emit a message, it will only be received by code for the same plugin that registers to hear it. So different plugins can use the same method and message names without conflict.
- A method call is always sent from
app-hosttosim-hostor vice versa (that is, a call fromapp-hostcan only be handled by a method registered onsim-host, and vice versa). - Emitted messages, on the other hand, are sent both "locally" and across to the "other side".
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent