New contributors

This page is aimed at people who are new to Mozilla and want to contribute to Mozilla source code related to Marionette Python tests, WebDriver spec tests and related test harnesses and tools. Mozilla has both git and Mercurial repositories, but this guide only describes Mercurial.

If you run into issues, check out the Resources section below and don't hesitate to ask questions. :) The goal of these steps is to make sure you have the basics of your development environment working. Once you do, we can get you started with working on an actual bug, yay!

Accounts, communication

  1. Set up IRC.
  2. Set up a Bugzilla account and a Mozillians profile. Please include your IRC nickname in both of these accounts so we can work with you more easily. For example, Eve Smith would set their Bugzilla name to "Eve Smith (:esmith)", where esmith is their IRC nick.
  3. Join #ateam or #automation on and introduce yourself to the whole team and :maja_zf. We're nice, I promise.

Getting the code, running tests

  1. Follow this tutorial to get a copy of Firefox source code and build it:

    If you're asked to run a 'bootstrap' script, choose the option "Firefox for Desktop Artifact Mode". This significantly reduces the time it takes to build Firefox on your machine (from 30+ minutes to just 1-2 minutes).

  2. Check if you can run any marionette tests: Use mach to run Marionette unit tests against the Firefox binary you just built in the previous step: ./mach marionette test -- see Running Marionette tests for details. If you see tests running, that's good enough: you don't have to run all the tests right now, that takes a long time.

    Fun fact: the set of tests that you just ran on your machine is triggered automatically for every changeset in the Mozilla source tree! For example, here are the latest results on Treeherder.

  3. As an exercise, try out this different way of running the Marionette unit tests, this time against Firefox Nightly instead of the binary in your source tree:

    • Download and install Firefox Nightly, then find the path to the executable binary that got installed. For example, on a macOS it might be something like FF_NIGHTLY_PATH=/Applications/
    • Create and activate a virtualenv environment.
    • Within your checkout of the Mozilla source, cd to testing/marionette/client.
    • Run python develop to install the marionette driver package in development mode in your virtualenv.
    • Next cd to testing/marionette/harness.
    • Run cd marionette && python tests/unit-tests.ini --binary $FF_NIGHTLY_PATH.
      • These are the same tests that you ran with ./mach marionette test, but they are testing the Firefox Nightly that you just installed. (./mach marionette tests just calls code in
    • Configure Mercurial with helpful extensions for Mozilla development by running ./mach mercurial-setup.
      • It should install extensions like firefox-trees and set you up to be able to use MozReview, our code-review tool.
      • If it asks you about activating the mq extension, I suggest you respond with 'No'.

Work on bugs and get code review

Once you've completed the above basics, ask :maja_zf, :whimboo, or :ato in #ateam for a good first bug to work on. (Or you can also take a look at the simple bugs listed on Bugs Ahoy.)

If you're an Outreachy applicant and you find that we're offline or "afk" on IRC, feel free to send Maja an email instead: [myfirstname] at -- either way, be sure to tell me which bug you are interested in for your application!

To work on the bug that is suggested to you and push a patch up for review, follow the Firefox Workflow in hg.

After testing your code locally, you will push your patch to be reviewed in MozReview. To set up MozReview, see this configuration page. (Note: the only kind of account you need for MozReview is Bugzilla (not LDAP) and you can only use HTTPS, not SSH.)


  • Sometimes (often?) documentation is out-of-date. If something looks off, do ask us for help!
  • Search Mozilla's hg repositories with DXR.
  • Helpful guide for new contributors. This is a good general resource if you ever get stuck on something. The most relevant sections to you are about Bugzilla, Mercurial, Python and the Development Process.
  • Mercurial for Mozillians
  • More general resources are available in this little guide I wrote in 2015 to help a student get started with open source contributions.
  • This guide provides a one-track, simple flow for getting started with Marionette Test Runner development. The general guide to all Marionette development is at
  • If you'd rather use git instead of hg, see git workflow for Gecko development and/or this blog post by :ato.