gecko-dev/testing/marionette/CONTRIBUTING.md

Contributing

We are delighted that you want to help improve Marionette! ‘Marionette’ means different a few different things, depending on who you talk to, but the overall scope of the project involves these components:

• Marionette is a Firefox remote protocol to communicate with, instrument, and control Gecko-based browsers such as Firefox and Fennec. It is built in to Firefox and written in XPCOM flavoured JavaScript.

  It serves as the backend for the geckodriver WebDriver implementation, and is used in the context of Firefox UI tests, reftesting, Web Platform Tests, test harness bootstrapping, and in many other far-reaching places where browser instrumentation is required.

• geckodriver provides the HTTP API described by the WebDriver protocol to communicate with Gecko-based browsers such as Firefox and Fennec. It is a standalone executable written in Rust, and can be used with compatible W3C WebDriver clients.

• webdriver is a Rust crate providing interfaces, traits and types, errors, type- and bounds checks, and JSON marshaling for correctly parsing and emitting the WebDriver protocol.

By participating in this project, you agree to abide by the Mozilla Community Participation Guidelines. Here are some guidelines for contributing high-quality and actionable bugs and code.

Writing code

Because there are many moving parts involved remote controlling a web browser, it can be challenging to a new contributor to know where to start. Please don’t hesitate to ask questions!

The canonical source code repository is mozilla-central. Bugs are filed in the [Testing :: Marionette] component on Bugzilla. We also have a curated set of good first bugs you may consider attempting first.

We have collected a lot of good advice for working on Marionette code in <doc/CodeStyle.md>, which we highly recommend you read. There is more development documentation archived under <doc/index.rst> that you may peruse at your convenience.

Building

Marionette is built in to Firefox and ships in the official Firefox binary. As Marionette is written in XPCOM flavoured JavaScript, you may choose to rely on so called artifact builds, which will download pre-compiled Firefox blobs to your computer. This means you don’t have to compile Firefox locally, but does come at the cost of having a good internet connection. To enable artifact builds you may choose ‘Firefox for Desktop Artifact Mode’ when bootstrapping.

Once you have a clone of mozilla-unified, you can set up your development environment by running this command and following the on-screen instructions:

% ./mach bootstrap

To perform a regular build, simply do:

% ./mach build

You can clean out the objdir using this command:

% ./mach clobber

Occasionally a clean build will be required after you fetch the latest changes from mozilla-central. You will find that the the build will error when this is the case. To automatically do clean builds when this happens you may optionally add this line to the mozconfig file in your top source directory:

mk_add_options AUTOCLOBBER=1

If you compile Firefox frequently you will also want to enable ccache and sccache if you develop on a macOS or Linux system:

mk_add_options 'export RUSTC_WRAPPER=sccache'
mk_add_options 'export CCACHE_CPP2=yes'
ac_add_options --with-ccache

Running tests

We verify and test Marionette in a couple of different ways. Marionette has a set of xpcshell unit tests located in testing/marionette/test*.js_. These can be run this way:

% ./mach test testing/marionette/test_*.js

Because tests are run in parallell and xpcshell itself is quite chatty, it can sometimes be useful to run the tests sequentially:

% ./mach test --sequential testing/marionette/test_error.js

These unit tests run as part of the X jobs on Treeherder.

We also have a set of functional tests that make use of the Marionette Python client. These start a Firefox process and tests the Marionette protocol input and output. The following command will run all tests:

% ./mach test mn

But you can also run individual tests:

% ./mach test testing/marionette/harness/marionette_harness/tests/unit/test_navigation.py

When working on Marionette code it is often useful to surface the stdout from Firefox:

% ./mach test --gecko-log - TEST

It is common to use this in conjunction with an option to increase the Marionette log level:

% ./mach test --gecko-log - -vv TEST

A single -v enables debug logging, and a double -vv enables trace logging.

As these are functional integration tests and pop up Firefox windows sporadically, a helpful tip is to surpress the window whilst you are running them by using Firefox’ headless mode:

% ./mach test -z TEST

-z is an alias for --headless and equivalent to setting the MOZ_HEADLESS output variable. In addition to MOZ_HEADLESS there is also MOZ_HEADLESS_WIDTH and MOZ_HEADLESS_HEIGHT for controlling the dimensions of the no-op virtual display. This is similar to using xvfb(1) which you may know from the X windowing system, but has the additional benefit of also working on macOS and Windows.

We have a separate page documenting how to write good Python tests in <doc/PythonTests.md>. These tests will run as part of the Mn job on Treeherder.

In addition to these two test types that specifically test the Marionette protocol, Marionette is used as the backend for the geckodriver WebDriver implementation. It is served by a WPT test suite which effectively tests conformance to the W3C specification.

This is a good try syntax to use when testing Marionette changes:

-b do -p linux,linux64,macosx64,win64,android-api-16 -u marionette-e10s,marionette-headless-e10s,xpcshell,web-platform-tests,firefox-ui-functional-local-e10s,firefox-ui-functional-remote-e10s -t none

Submitting patches

You can submit patches by uploading .diff files to Bugzilla or by sending them to MozReview.

Once you have contributed a couple of patches, we are happy to sponsor you in becoming a Mozilla committer. When you have been granted commit access level 1 you will have permission to use the Firefox CI to trigger your own “try runs” to test your changes.

Communication

The mailing list for Marionette discussion is tools-marionette@lists.mozilla.org (subscribe, archive).

If you prefer real-time chat, there is often someone in the #ateam IRC channel on irc.mozilla.org. Don’t ask if you can ask a question, just ask, and please wait for an answer as we might not be in your timezone.