gecko-dev/testing/marionette/doc/NewContributors.md

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 or have doubts, 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, if you like, 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 on irc.mozilla.org and introduce yourself to the team. :ato, :AutomatedTester, :maja_zf and :whimboo are all familiar with Marionette. We're nice, I promise, but we might not answer right away (different time zones, time off, etc.).

4. When you want to ask a question on IRC, just go ahead an ask it even if no one appears to be around/responding. Provide lots of detail so that we have a better chance of helping you. If you don't get an answer right away, check again in a few hours -- someone may have answered you in the mean time.

5. You can view IRC logs on logbot to check if anyone has answered your question while you were offline.

6. If you're having trouble reaching us over IRC, you are welcome to send an email to our mailing list instead. It's a good idea to include your IRC nick in your email message.

Getting the code, running tests

1. Follow this tutorial to get a copy of Firefox source code and build Firefox for Desktop.

   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/FirefoxNightly.app/Contents/MacOS/firefox-bin.

   • Create and activate a virtualenv environment.

   • Within your checkout of the Mozilla source, cd to testing/marionette/client.

   • Run python setup.py develop to install the marionette driver package in development mode in your virtualenv.

   • Next cd to testing/marionette/harness.

   • Run cd marionette && python runtests.py 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 test just calls code in runtests.py).

   • Configure Mercurial with helpful extensions for Mozilla development by running ./mach vcs-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

See <Patches.md> on how to submit patches.

Resources

• Sometimes (often?) documentation is out-of-date. If something looks off, do ask us for help!

• This document provides a one-track, simple flow for getting started with Marionette Test Runner development. The general guide to all Marionette development is at Contributing

• Search Mozilla's hg repositories with searchfox.

• Another guide for new contributors. It has not been updated in a long time but it's 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 :maja_zf wrote in 2015 to help a student get started with open source contributions.

  • Textbook about general open source practices: Practical Open Source Software Exploration

• If you'd rather use git instead of hg, see git workflow for Gecko development and/or this blog post by :ato.