Emulating PhoneGap/Cordova Apps in the Desktop Browser

Earlier this month the PhoneGap team held the first PhoneGap day.  This was in part to celebrate the release of PhoneGap 2.0, but more importantly to bring together members of the PhoneGap community to share and learn from each other.   There are great recaps of PhoneGap Day from RedMonk, as well as on the PhoneGap blog. One of the new services announced on PhoneGap Day was emulate.phonegap.com.  Emulate.phonegap.com enables an in-browser simulator for developing and debugging PhoneGap/Cordova applications, complete with Cordova API emulation.  It is built off of the Ripple Emulator, which itself is open source and may even be contributed to the Apache Cordova project.

Emulate.phonegap.com is built as a Google Chrome Extension, so it requires the Chrome browser.  It also uses the Ripple Operating Environment (another Chrome Extension).   Once you have the dependencies installed you can emulate any site as a PhoneGap/Cordova application by either going to emulate.phonegap.com and entering the target URL, by launching the emulator from a right-click -> Emulator -> Enable, or by clicking on the Ripple icon in the Chrome toobar, and selecting the “Enable” option.

Once launched, the URL that you want to simulate will be displayed within the Ripple operating environment view.

Note: This only works with assets that are on a live URL. You can use a local http server with references to localhost, however the emulator will fail if you try to access your application directly from the local file system using a file:// URI.

Update: You can enable access to local files by changing a few settings on the Ripple emulator.  See the first comment on this post for additional detail.

(click for full-size image)

The emulator environment gives you the ability to emulate PhoneGap events and API calls, without having to deploy to a device or run inside of the iOS, Android, Blackberry, or other emulator.  Not only can you simulate the PhoneGap/Cordova API, but you can also use Chrome’s debugging tools to test & debug your code – complete with breakpoints, memory inspection, and resource monitoring. This is a handy development configuration. It enables app development within a rich debugging environment that is familiar, fast & easy to use. This does not replace on-device debugging however… nothing will replace that.   On-device debugging is extremely important; this helps increase your productivity as a developer.

So how do you use this environment? The environment will handle Cordova API requests, and you can also simulate device events.

First, the “Devices” panel… In this panel you can select a device configuration – Everything from iOS, to Android, to BlackBerry.  Changing the device configuration will not only change the physical dimensions, but will also change Device/OS/user agent settings reported by the application.   Here you can also select the device orientation, which will change the visual area within the simulator.

Within the “Platforms” panel you can choose the platform you wish to emulate.  With respect to PhoneGap applications, you will want to choose “Apache Cordova”, and then select the API version that you are using.  By default, it uses “PhoneGap 1.0.0”, however you can chose “Apache Cordova 2.0.0” to get the most recent version.   The Ripple emulator also simulates BlackBerry WebWorks and mobile web configurations as well.

The “Information” panel shows you information about your current simulator configuration.  It shows the platform, device, simulated OS, user agent etc…

The “Accelerometer” panel can be used to simulate device orientation/accelerometer events.  Just click and drag on the device icon (the gray and black boxes), and the icon will rotate in 3D.   As you drag, accelerometer events will be dispatched and handled within your application.  From here, you can even trigger a “shake” event.

The “Settings” panel lets you turn on/off the cross domain policy, adjust the UI color theme, and view additional data about the Ripple emulator.

The “Device & Network Settings” panel enables you to simulate and throttle the network connection type: “Ethernet”, “WIFI”, “CELL_3G”, etc…

The “Geolocation” panel enables you to simulate your geographic position within your PhoneGap/Cordova application.  You can specify a latitude, longitude, altitude, speed, etc…  You can even drag the map and use it to specify your geographic position. The position that you set within the geolocation panel will be reported when using navigator.geolocation.getCurrentLocation().

The “Config” panel is a graphical representation of your PhoneGap Build Config.xml file.   You can use this to easily view/analyze what’s in your application configuration.

The “Events” panel can be used to simulate PhoneGap specific events, including “deviceready”, “backbutton”, “menubutton”, “online”, and “offline” (among others).  Just select the event type, and click on the “Fire Event” button.

As I mentioned earlier, this won’t replace on-device debugging.  It also won’t handle execution of native code for PhoneGap native plugins, however you can test/develop against the JavaScript interfaces for those native plugins.  Emulate.phonegap.com will definitely help with development of PhoneGap applications in many scenarios, and is a nice complement to the Chrome Developer Tools.

  • http://developer.blackberry.com/html5 Dan Silivestru

    Hey Andrew,

    Great post, thanks so much for doing a write up on Ripple.

    Just wanted to mention quickly that you can actually run off of the file:/// scheme, just need a couple of steps:

    1. you need to close chrome and then start it with the –allow-file-access-from-files flag

    2. go to chrome://extensions page, find Ripple and check off the “Allow access to file URLs” checkbox

    3. enable Ripple as you describe and it should all work

    Finally, I also wanted to mention that we do have support for custom plugins in Ripple (under the Cordova platform only). If a call is made through to exec() in Cordova that Ripple does not know about, it will present you with a popup dialogue where you can enter the expected return JSON and then manually call your success or fail callbacks. You can see this at work if you enable ripple over this URL and then click the button: http://dansilivestru.github.com/phonegap-day-slides/#/19

    Again, great post 🙂


    • http://www.tricedesigns.com Andrew

      Thanks Dan! This is very helpful. I was not aware of the file:/// URI support in the Ripple emulator. So that other readers understand clearly: the plugin support in the Ripple emulator allows you to invoke the native plugin’s JS interface and allows you to specify a return value, but there is no execution of any native code. This is great for debugging the native plugin’s “hooks” into your application.

  • Brad

    If you dont want to setup the file path you can use httpster to create a local file server from any directory.

    check it out here. http://simbco.github.com/httpster/

    • http://www.tricedesigns.com Andrew

      On OSX, you can also open up a terminal, go to the appropriate folder, and enter this command: python -m SimpleHTTPServer 8000 This will start a http server rooted in whatever folder that you launched it in.

  • http://www.appocentric.com Per Quested Aronsson


    It would seem as one should exclude the reference to the cordova Javascript file when working in Ripple..?

    Am I right here? If not, where should I get this file from, and which dependencies exist?

    Thanks for good articles!
    Per Q A

    • http://www.tricedesigns.com Andrew

      You can have it in there, but I don’t think that you HAVE to have it. I have sample apps that include the cordova.js file. However, I think the emulator overrides it. Just make sure that you select the correct platform and version in the emulator window for it to behave properly:
      Emulator Platform
      You get the cordova.js file as part of the download from phonegap.com/download

  • daniel silivestru

    You shouldn’t comment out the cordova.js file, for Cordova 2.x, ripple’s emulation happens below the exec(…) call, so we actually depend on Cordova.js being there. This is so that you’re testing the exact same code base as you would be packaging up to put on the device.

    I think the confusion stems from the fact that in our emulation of PhoneGap 1.x we do completely override the phonegap.js file and recommend that you comment that file out.

    We had to do this in the past before the massive refactoring of Cordova to the unified JS project. However, we the new structure in Cordova.js today, we can take the much more elegant approach to emulation as mentioned in my first paragraph.

    Hope this helps clear things up 🙂

  • meme

    im computer system engineering student , and my graduation project is building cross plat form application
    and after made alot of searches about the best tool , i choose phonegap
    now , i want to convince my instructor why i choose the phonegap
    i made simple application , i wanna to test the emulator , and i read allot of articles , actually im not really understanding , how the html file could load to the Ripple emulator
    plz help me ASAP

  • meme

    thanks too much
    i try it and it’s work
    i have a question
    it seems that the simulator work with chrome
    is it possible to work with another browser , like Firefox ?

    • http://www.tricedesigns.com Andrew

      No it is not possible to use another browser. The PhoneGap/Ripple emulator is built as a Google Chrome plugin.

    • Thirtified

      Yes, you can: check out the Apache Ripple project. It has a npm package ripple-emulator which runs a local web server for your application and injects all the Ripple happiness to use in any browser you want.

      npm install -g ripple-emulator
      ripple emulate --port 1234 --path path/to/my/application/root

      • http://www.tricedesigns.com Andrew

        Thanks for sharing! This can be very helpful for anyone not running Chrome.

  • afields

    very good piece of soft! i’m making some tests and they include the creation of a database. As it is needed to have some tables and also records i thought it would be possible, with sqlitemanager to create those tables and records. but where do i find the database create with emulator phonegap?

    • http://www.tricedesigns.com Andrew

      You must create your tables using JavaScript in the application (SQLLite syntax). Details: http://docs.phonegap.com/en/2.7.0/cordova_storage_storage.md.html#Storage You can change data using SQL queries inside the Chrome Developer Tools.

      • Afields Campos

        thank you Andrew. i’m working on it… however another question:

        I want to populate several tables from a database with data that’s in text file. I wanted to emulate that but it’s not working. how can i indicate the path of a file with emulator and where should that file be?

        thx again!!

  • Gopal Agrawal

    Good tutorial. Thanks.

  • DanTheMan

    Hi a few months too late possibly.

    Can you use the emulator to test upload to server using ajax in phonegap?

  • Bhaskar Gandavabi

    Does Ripple support “Media” plugin? I am trying to some audio playing functionality in Ripple, doesn’t seem to work, keep getting Media is not defined

  • Gene Mishchenko

    Andrew, I think you have to have the “cordova.js” file executed in your application AND it has to match the version supported by the Ripple Emulator (2.0.0 as of right now) for it to work properly.

    PhoneGap Build, on the other hand, does not need it, as it automatically replaces it with the latest version.

    Until I placed the file there, the “deviceready” event could not be triggered for my emulated device. In Cordova documentation it is strongly advised to not execute anything in the Web part of the application until the “deviceready” event is received. It’s a dependency that you want to enforce in your code, therefore you do need the script executed.

    According to the below post on StackOverflow, there may be other dependencies as well. It has the full explanation and the full set of instructions:


  • eslachance

    I don’t know if I’m missing anything but the greatest majority of the thigns I’d like to test seem ignored by the emulator. The date selector doesn’t work, there`s no way to simulate pictures, signatures (SVG note taking, basically) doesn’t work… Am I missing something?

  • chandan khatri

    Hi Andrew,

    Thanks for sharing such informative and easy to understand post.
    I am also using ripple and app is based on MEAN + phonegap. The app works fine on mobile browser and ripple emulator but doesn’t work properly when installed on android emulator or device. Any idea how I can debug this issue. I googled but didn’t find much info.