Developer setup

Get the Code

Both the marionette server and client code is managed in mozilla-central, so please follow this guide to install mercurial. Once that is done, you can now clone our source code (called mozilla-central):

hg clone http://hg.mozilla.org/mozilla-central/

Which will create a folder called 'mozilla-central' that contains our source code. NOTE: mozilla-central is a *very large* repository, you will need to have about 2GB of space available. This repository holds the code for not just Marionette, but all of Firefox and supporting projects.

 

Once you have the codebase, you should set up Mercurial Queues. This will help you manage your patches and let you submit properly formatted patches.
 

Get a Marionette-enabled Build

You'll need a version of Firefox with marionette built into it.

If you're writing code for the marionette server (JS code)

You should make your own Firefox build. You can build your own by following instructions here.

If you're writing code for the marionette client (python)

You can download a build with marionette installed. We have them available to you as nightly debug builds, and you can download them for your environment at our FTP site. Download a build from mozilla-central-debug. NOTE: If you're on windows, you'll need to install visual C++ in order to have all the DLLs required to run a debug build. Follow instructions on which VS product to download here according to your machine.

For example, for May 15th's mac build:
ftp://ftp.mozilla.org/pub/firefox/nightly/2013/05/2013-05-15-mozilla-central-debug/

Or if you'd like to use it against the emulator/device/other, use set it up using this guide.
ftp://ftp.mozilla.org/pub/firefox/nightly/2013/

 

Once you have the build, install it, and keep note of the installation directory. You'll need it in the following steps.

Getting it all hooked up

I strongly recommend using virtualenv when working in python. To install it run 'pip install virtualenv'. If you do not have pip, you can get it using 'easy_install pip'

Once you have this, go into the mozilla-central source code you downloaded and do:

  cd testing/marionette/client/

  virtualenv venv

  source venv/bin/activate

  python setup.py develop


Now you will have a marionette-client installed in your virtual environment! To test out if everything is in working order, let's run a sample test.

 

To do this, you'll need to know where the firefox-bin lives in the Firefox version you downloaded/built. If you built it, it will be in your object directory: (object directory)/dist/bin/firefox-bin.

If you built or downloaded your build earlier

If you downloaded the build (Nightly), you'll have to find the path to the executable inside the installation directory you made note of earlier. For mac, it's FirefoxNightlyDebug.app/Contents/MacOS/firefox-bin; for linux, once you untar the file, it should be firefox/firefox-bin. For windows, it will be firefox.exe, located in the directory you installed Nightly in. Once you have the path, follow these steps to run a test

 cd (mozilla-central)/testing/marionette/client/marionette/
 
 python runtests.py --binary=<path to firefox executable> tests/unit/test_execute_script.py
 

Note: If you're using windows, if you're using the shell provided by mozilla-build, instead of using "C:\<path using \ slashes>" type file paths, you should use "/c/<path using / slashes>".

Starting a Marionette-Enabled Firefox without runtests.py

The instructions in the previous section start a Firefox instance using runtests.py (ie: our test runner). You can start your own Firefox instance with marionette running. All you need is to create a Firefox profile with marionette preferences enabled. It is recommended that you create a profile just for testing (separate from your default browsing one), so that if anything goes wrong, you can just create a new test profile.

To create a profile, you need to start the profile manager. To do that, you'll need to find the path to your firefox executable inside the installation directory you made note of earlier. For mac, it's FirefoxNightlyDebug.app/Contents/MacOS/firefox-bin; for linux, once you untar the file, it should be firefox/firefox-bin. For windows, it will be firefox.exe, located in the directory you installed Nightly in. Once you have the path, follow these steps to run a test

and run the following:

<path to executable> -P


You'll then be presented with the profile manager window. Click the 'Create Profile...' button and create a new profile, then select that new profile and click 'Start Firefox'. You'll now have a Firefox instance started with your brand new profile! Note: the next time you start Firefox, it will use the default profile, not the one you just created. You have to use the instruction above to use this test profile again.

In the Firefox address bar, type in 'about:config' and hit enter. Accept the warning, and you'll be presented with a large list of preferences. You will need to add the following preferences to about:config (right click on the page to create a new entry). The first is a boolean, the second is a string. The -> indicates the mapping of the name to the value:

marionette.defaultPrefs.enabled -> true
marionette.defaultPrefs.port -> 2828

Your test profile is now ready to go. You will only ever need to set these preferences ONCE per profile, so don't worry about repeating this step.

 

Now, since the Marionette server starts when Firefox starts up, you'll need to restart firefox with this profile. Close this Firefox instance, and start up the profile manager again:

<path to executable> -P

Select the test profile you created and click 'Start Firefox'. Marionette should now be started!

 

You can verify if Marionette has started by checking the port it is running on. By default, it runs on port 2828. You can use Telnet to check:

telnet localhost 2828

If there is a Marionette server running, you'll see something like:

Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
66:{
  "from": "root",
  "applicationType": "gecko",
  "traits": []
}

 

If there is no Marionette server running, you'll see a lot of "telnet: connect to address fe80::1: Connection refused" messages

Running tests

To run tests against an existing Marionette server, you'll need to change directories into our client code:

 cd (mozilla-central)/testing/marionette/client/marionette/
 

Note: If you're using windows, if you're using the shell provided by mozilla-build, instead of using "C:\<path using \ slashes>" type file paths, you should use "/c/<path using / slashes>".

To run the tests, you'll need to call 'runtests.py' with the --address parameter set to the Marionette server host and port like so:

 python runtests.py --address=localhost:2828 tests/unit/test_execute_script.py

If you're using a device or b2g desktop

If you're using a different environment, you can run it using the following command. If you're using a phone with marionette, you'll need first run 'adb forward tcp:2828 tcp:2828' before doing this to make sure the port is forwarded: python runtests.py --address=localhost:2828 tests/unit/test_execute_script.py

 python runtests.py --address=localhost:2828 tests/unit/test_execute_script.py

 

Parts of the Codebase

Server

If you're working on the server code, all the marionette bits you need live in (mozilla-central)/testing/marionette/ as .js files. 

Once you've made changes, you can build them into your version of firefox by running:

make -C (objdir)/testing/marionette

where (objdir) is the path to your object directory.

If you've updated your repository since you last built (ie: if you ran 'hg pull -u' or 'hg pull' and 'hg update'), then you'll need to rebuild:

cd (mozilla-central)
./mach build

where (mozilla-central) is the top of your mozilla-central repository

Important Concepts

Essentially, in the browser, there are two places you can interact with: 'content' and 'chrome'. Content is the websites you interact with, all the html and the webpage's DOM.

Chrome is the browser specific stuff like the navigation bar and the scrollbar, ie, the things that live outside of the webpage itself. Code that is executed here has many privileges, privileges that code in content space doesn't have access to, like creating local files.

Marionette can run commands against the content of a webpage and against the chrome, ie: the browser part of the webpage. The client can send commands to either the content or the chrome of a window. The server is able to manage that using two components: marionette-server.js and marionette-listener.js

marionette-server.js is what manages all the 'chrome' facing code. This is where the client connection is managed, and where any commands that's being executed against the chrome of a webpage gets handled. If the client wishes to execute commands against the content, then marionette-server.js sends the command to marionette-listener.js to be handled.

marionette-listener.js is a file loaded per window, and it handles all content commands sent to this window.

Client

If you're working on the client code, you'll be working in (mozilla-central)/testing/marionette/client/

Style  Guide

Javascript

Please follow the style of the file you're working on. We use a "tab width" of 2 spaces (we do not use actual tabs).

Python

We attempt to follow the PEP-8 style guide, but in general, follow the style of the file you're working on. We use a "tab width" of 4 spaces (we do not use actual tabs).

Once you have a patch ready...

First, check that the patch applies cleanly on mozilla-central. To do this, pop off your patch from the patch queue

hg qpop

Then update your mozilla-central:

hg pull -u

Then reapply your patch:

hg qpush

If your patch has conflicts, look at the .rej files to see where the conflicts are and resolve them in their respective files. Once you've resolved all your conflicts, update your patch by running:

hg qrefresh

Repeat the previous popping/updating/pushing again to make sure this new patch applies cleanly.

 

 Once you have a clean patch, add the patch as an attachment to the bug you're working on, and while attaching it, add a review flag. To do this, under the Flags section and next to "review" is a dropdown menu. Select "r?" and in the textbox, enter your mentor's IRC nick. There will be a dropdown selection of email addresses, so flag the right mentor.

Document Tags and Contributors

Contributors to this page: Sheppy, mdas, mrcote, fscholz
Last updated by: fscholz,