We support a number of automation tools that use the Marionette JS Client. This article describes some of the ongoing work to help JavaScript consumers leverage gecko's marionette server. If you're feeling lost at this point, head over to Marionette for a broad overview (and then come back ;).
Motivation
We would like to
- write integration tests in gaia that test user interfaces,
- access privileged (i.e. chrome) APIs in our tests,
- write our integration tests in JavaScript (!),
- be able to write small, modular test helpers that can be reused (perhaps even outside of Firefox OS),
- be agnostic to whether test writers would like synchronous or asynchronous APIs,
- support a wide variety of different test environments (currently desktop firefox and b2g-desktop).
Marionette JS Client
- An interface for JavaScript consumers to make calls into gecko's marionette server
- Designed to run on NodeJS
- Documentation here
- Allows both synchronous and asynchronous marionette method invocations
- Provides a plugin hook which allows other libraries to extend its functionality seamlessly
Marionette JS Client Plugins
Plugins can extend the JS client's core functionality by registering with the client and binding hooks to different client events (ie startSession). In addition, plugins are expected to implement the following method so that the client can initialize them:
/**
* Initialize my plugin.
* @param {Marionette.Client} client marionette js client to extend.
* @param {Object} options map of named args for the plugin.
*/
MyPlugin.setup = function(client, options) {};
Below are some examples of existing client plugins!
Marionette Apps
The marionette apps plugin provides some useful functions for interacting with apps (ie #list, #launch, #switchToApp, #close). You will likely find this abstraction useful if you are writing integration tests for a Firefox OS app. Under the hood, this plugin calls into the App Installation and Management APIs via the marionette client.
Marionette JS Logger
The marionette js logger plugin proxies console.* calls made from a child gecko process directly to a node parent process.
Marionette Host
We're also working to automate the process of hooking up the client with various marionette-enabled gecko instances (firefox, b2g-desktop, devices, etc). We currently support spawning a configurable, marionette-enabled desktop firefox and b2g-desktop instances.
Mocha Hacking
In order to provide a really simple way for test writers to leverage marionette in mocha and target different platforms, we wrapped a lot of our work together in Marionette JS Runner, a mocha wrapper that manages separate child, gecko processes to run tests on different platforms.
Marionette JS Tests on Travis and TBPL
Our tooling is 100% compatible with Travis CI out of thebox. Additionally, in order to hack our final product to report build results to Treeherder and since we've used the Mocha testing framework for our work, we built a mocha-tbpl-reporter.
Get in Touch
To ask questions, contribute, etc hit us up on e-mail or IRC (in the #gaia channel on concrete.mozilla.org).
James Lal, jlal@mozilla.com, lightsofapollo
Gareth Aye, gaye@mozilla.com, gaye
Mike Pennisi, mike@bocoup.com, jugglinmike