Part 1: Getting started with Marionette and Firefox OS

This tutorial series aims to get you onboard with writing and running automated UI tests for Firefox OS using Marionette, an automation package that runs on your computer. Marionette issues commands to run tests on Gecko-based platforms. This particular article will run you through the set up you need to do to before you can start running tests.

The tutorial series will walk through automated testing concepts and also introduce you to working with Firefox OS (including the rather useful B2G Desktop testing tool) and Marionette. Occasionally we will include challenges to encourage you to explore your own solutions.

Note: The tutorial is not specific to Mozilla products; if you are developing an HTML5 app for example, you can use this tutorial to build up a test framework.

Software required for this tutorial

During the tutorial we will install and use the following software:

  • Python 2.7
  • pip installer
  • A text editor or IDE to write code in
  • The Boot2Gecko desktop client (Firefox OS)
  • The Marionette client (WebDriver client for Firefox OS)

Python and pip

Some operating systems like Linux will come with Python pre-installed. Before installing Python, check that you don't already have it installed. From a command line or terminal, run:

python --version

Any version of Python 2.6.x or 2.7.x is fine for this tutorial. If you don't have Python 2.7 installed then you can find the installer on the Python release site.

Pip is used to install Python tools and we need it to install Marionette. You can check whether pip is installed by typing pip into your terminal or command line. To install pip, follow the instructions in the pip documentation.

B2G Desktop

The B2G Desktop client allows you to run Gaia — Firefox OS's UI — and Firefox OS apps on a desktop or laptop computer. There are certain limitations of the desktop client — it doesn’t emulate device hardware such as camera, battery, etc. — but it will be perfect for our purposes in this tutorial. Let's get this installed next.

Download the latest B2G desktop from the Firefox Nightly site (see Desktop Boot2Gecko, at the bottom.) Once B2G Desktop is downloaded, extract the contents to a folder on your computer. To start the Firefox OS simulator run the b2g script file appropriate for your OS:

  • Linux: Navigate to the folder where you extracted it and run ./b2g
  • Mac: Drag and drop into your Application folder and run it from there.
  • Windows: Run b2g.exe from inside the directory you extracted the zip to.

Once the application starts up, you should be able to see a window similar to this:

A welcome screen for Firefox OS - says welcome in multiple languages

Follow the First Time Usage steps until you get to the Firefox OS homescreen. Note that you can emulate the phone hardware buttons using the following keyboards commands, which can be quite useful (for example, pressing home to wake the phone up from sleep.)


Windows/Linux keyboard

Mac OS keyboard

Home button


Fn+left arrow

Power button


Fn+right arrow

Volume up/down

Page up/page down

Fn+ up/down arrow

At this point you can leave B2G Desktop open and move the window to the side. Next we'll finish the job by getting Marionette installed.


Marionette consists of two parts; the client — which operates on your laptop — and the server — which operates within Firefox OS. Marionette server, like a puppeteer, can then control Firefox OS directly.

marionette architecture showing marionette server inside Firefox OS and marionette client on its own outside

Since we are using the Desktop B2G client, the Marionette server is pre-installed (this is also true when you are using an engineering-configured build of Firefox OS for a real device.) Before we can control Firefox OS however, we need to install the Marionette client on our local computer. This is done by running the following command in your terminal:

pip install marionette_client

That's it for now. We are set up and ready to go!