Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-12-12 09:01:16 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1494229 - [marionette] Improve documentation for new contributors. r=ato

Browse Source 
DONTBUILD

Differential Revision: https://phabricator.services.mozilla.com/D8981

--HG--
extra : moz-landing-system : lando
This commit is contained in:
Henrik Skupin 2018-10-18 19:06:25 +00:00
parent e9047f00f5
commit 50aaf57a2b
3 changed files with 36 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
testing/marionette/doc/Building.md
View File

@ -16,6 +16,11 @@ on-screen instructions:
% ./mach bootstrap
When you're getting asked to choose the version of Firefox you want to build,
you may want to consider choosing "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) if you have a fast internet connection.
To perform a regular build, simply do:
% ./mach build
@ -39,7 +44,7 @@ If you compile Firefox frequently you will also want to enable
mk_add_options 'export CCACHE_CPP2=yes'
ac_add_options --with-ccache
[mozilla-unified]: https://hg.mozilla.org/mozilla-unified/
[mozilla-unified]: https://mozilla-version-control-tools.readthedocs.io/en/latest/hgmozilla/unifiedrepo.html
[artifact builds]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds
[ccache]: https://ccache.samba.org/
[sccache]: https://github.com/mozilla/sccache

108
testing/marionette/doc/NewContributors.md
View File

@ -16,17 +16,18 @@ actual bug, yay!
Accounts, communication
-----------------------
1. Set up [IRC].
1. 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 the Bugzilla name
to "Eve Smith (:esmith)", where "esmith" is the IRC nick.
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.
2. For a direct communication with us it will be beneficial to setup [IRC].
Make sure to also register your nickname as described in the linked document.
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.).
3. Join our #ateam channel, 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 due to different
time zones, time off, etc. So please be patient.
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.
@ -49,93 +50,28 @@ Accounts, communication
Getting the code, running tests
-------------------------------
1. Follow this [tutorial](http://areweeveryoneyet.org/onramp/desktop.html)
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'.
[mach]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/mach
[Marionette]: index.html
[Running Marionette tests]: PythonTests.html
[latest results on Treeherder]: https://treeherder.mozilla.org/#/jobs?repo=mozilla-inbound&filter-job_type_symbol=Mn
[Firefox Nightly]: https://nightly.mozilla.org/
[virtualenv]: https://www.dabapps.com/blog/introduction-to-pip-and-virtualenv-python/
[testing/marionette/client]: https://searchfox.org/mozilla-central/source/testing/marionette/client
[testing/marionette/harness]: https://searchfox.org/mozilla-central/source/testing/marionette/harness
Follow the documentation on [Contributing](Contributing.html) to get a sense of
our projects, and which is of most interest for you. You will also learn how to
get the Firefox source code, build your custom Firefox build, and how to run the
tests.
Work on bugs and get code review
--------------------------------
See <Patches.md> on how to submit patches.
Once you are familiar with the code of the test harnesses, and the tests you might
want to start with your first contribution. The necessary steps to submit and verify
your patches are layed out in [Patches.md](Patches.html).
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](Contributing.html)
* Search Mozilla's hg repositories with [searchfox].
* Search Mozilla's code 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
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]
@ -143,8 +79,7 @@ Resources
* 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]
* 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].
@ -156,4 +91,3 @@ Resources
[Practical Open Source Software Exploration]: https://quaid.fedorapeople.org/TOS/Practical_Open_Source_Software_Exploration/html/index.html
[git workflow for Gecko development]: https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development
[this blog post by :ato]: https://sny.no/2016/03/geckogit
[git workflow for Gecko development]: https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development

12
testing/marionette/doc/Testing.md
View File

@ -15,6 +15,9 @@ distinct components that we test:
- and the **harness** that backs the Marionette, or `Mn` job on
try, tests is verified using separate mock-styled unit tests.
All these tests can be run by using [mach].
[mach]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/mach
xpcshell unit tests
-------------------
@ -37,7 +40,7 @@ These unit tests run as part of the `X` jobs on Treeherder.
Marionette functional tests
---------------------------
We also have a set of functional tests that make use of the Marionette
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, and will appear as `Mn` on Treeherder.
The following command will run all tests locally:
@ -48,9 +51,9 @@ But you can also run individual tests:
% ./mach marionette test testing/marionette/harness/marionette_harness/tests/unit/test_navigation.py
In case you want to run the tests with another Firefox binary:
In case you want to run the tests with another binary like [Firefox Nightly]:
% ./mach marionette test --binary /path/to/firefox TEST
% ./mach marionette test --binary /path/to/nightly/firefox TEST
When working on Marionette it is often useful to surface the stdout
from Gecko, which can be achived using the `--gecko-log` option.
@ -72,6 +75,9 @@ 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.
[functional tests]: PythonTests.html
[Firefox Nightly]: https://nightly.mozilla.org/
### Android