Testing in a privileged context: Shipping your own Gaia apps

As you may have noticed, executing JavaScript does not give you full access to all the shiny WebAPIs. For an app to use a specific API, it has to request access to that API in its manifest. This article takes you through how to test privileged apps before they are submitted to a Marketplace.

To obtain the currently running app's metadata and manifest into a variable, you can use code like this:

navigator.mozApps.getSelf().onsuccess = function(e) {
  appself = e.result;
}

This fetches the app's metadata into the variable appself.

On a similar note, if you want to see the permissions for a different app, take a look at the test app "Permissions", which comes with your b2g-desktop testing build: it enumerates the permissions given to all of the currently-installed apps.

Some of the existing WebAPIs are just not available to any kind of app. To use these APIs, you need to install an app with the highest privileges (that is, a certified app). To do that yourself, you have to build a custom version of the top b2g layer, Gaia. Doing this requires git and a working make environment. See Firefox OS build prerequisites for details on setting up a Firefox OS build environment.

In this case, you don't need to build all of Firefox OS, just Gaia. Let's see how you do that.

Downloading and building Gaia

First, you need to download Gaia then build it. This creates a profile you can load with b2g desktop. This can be done using the following commands:

$ git clone https://github.com/mozilla-b2g/gaia
$ cd gaia
$ make

Warning: Building Gaia for the first time requires downloading XULRunner, which is about 500 MB, so it takes some time and a lot of space.

This will build the standard Gaia for you, so that it's ready for action.

Preparing a custom app

While XULRunner is being downloaded, I recommend reading the Gaia source code. You can be getting your custom app ready while this download progresses.

All the apps that come with Gaia (Settings, Contacts, Browser, etc.) are stored in the apps/ directory. That means that your high-privileged app will also have to go there. For the purposes of this article, an example app called allperms has been made available on Github.

Change into the apps/ directory in your Gaia code tree and clone the example app into it:

cd apps
git clone https://github.com/freddyb/allperms.git

Once your first Gaia build is done and xulrunner-sdk has been downloaded, you can rebuild Gaia with allperms in the apps/ directory. But don't worry, this time the build will be much faster, since most things have already been compiled. Just do:

make

Load B2G desktop using the new profile

B2G Desktop comes with two main executables: b2g and b2g-bin: we want the latter, as this allows us to specify command line arguments.

Note: See Using the B2G desktop client for additional information about the B2G Desktop application.

Load the b2g executable, supplying the -profile option with the path to the Gaia profile you've just built.

Linux

$ b2g-bin -profile /path/to/gaia/profile 

Mac OS X

On Mac OS X, the command to launch from the gaia directory (assuming you've installed B2G in the standard applications folder) is as follows:

$ /Applications/B2G.app/Contents/MacOS/b2g-bin -profile /path/to/gaia/profile 

Windows

TBD

What to expect

Assuming it all works, you should see the lock screen:

There are some useful command-line options available when using B2G Desktop.

Note: This profile starts with default settings again. Any customizations you have to your testing setup will have to be done again; this includes configuration of Marionette, proxies, and certificates.

Done

Your allperms app should now be installed and should be equipped with all possible permissions.

Now you will only have to re-iterate on the Marionette steps from Debugging and security testing with Firefox OS to have a testing environment that can access all WebAPIs.

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, kechol, jswisher, Sheppy, freddyb
 Last updated by: chrisdavidmills,