Bug 1458742 - Add documentation for marionette.* prefs. r=maja_zf
authorAndreas Tolfsen <ato@sny.no>
Wed, 02 May 2018 17:31:25 -0700
changeset 473104 e8fb1c6b25972542dcbf9afb16a4cc9fc4cb6a09
parent 473103 169687fc666d12c9dac44f8ef1ad091bae62f7b5
child 473105 c5980d2f915f2999b051fac21f859c769df2b98b
push id1728
push userjlund@mozilla.com
push dateMon, 18 Jun 2018 21:12:27 +0000
treeherdermozilla-release@c296fde26f5f [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmaja_zf
bugs1458742
milestone61.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1458742 - Add documentation for marionette.* prefs. r=maja_zf MozReview-Commit-ID: HRWkFQtlsEv
testing/marionette/doc/Prefs.md
testing/marionette/doc/index.rst
new file mode 100644
--- /dev/null
+++ b/testing/marionette/doc/Prefs.md
@@ -0,0 +1,73 @@
+Preferences
+===========
+
+There are a couple of preferences associated with the Gecko remote
+protocol:
+
+
+`marionette.enabled`
+--------------------
+
+Starts and stops the Marionette server.  This will cause a TCP
+server to bind to the port defined by `marionette.port`.
+
+If Gecko has not been started with the `-marionette` flag or the
+`MOZ_MARIONETTE` environment variable, changing this preference
+will have no effect.  For Marionette to be enabled, either one of
+these options _must_ be given to Firefox or Fennec for Marionette
+to start.
+
+
+`marionette.debugging.clicktostart`
+-----------------------------------
+
+Delay server startup until a modal dialogue has been clicked to
+allow time for user to set breakpoints in the [Browser Toolbox].
+
+[Browser Toolbox]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox
+
+
+`marionette.log.level`
+----------------------
+
+Sets the verbosity level of the Marionette logger repository.  Note
+that this preference does not control the verbosity of other loggers
+used in Firefox or Fennec.
+
+The available levels are, in descending order of severity, `trace`,
+`debug`, `config`, `info`, `warn`, `error`, and `fatal`.  The value
+is treated case-insensitively.
+
+
+`marionette.port`
+-----------------
+
+Defines the port on which the Marionette server will listen.  Defaults
+to port 2828.
+
+This can be set to 0 to have the system atomically allocate a free
+port, which can be useful when running multiple Marionette servers
+on the same system.  The effective port is written to the user
+preference file when the server has started and is also logged to
+stdout.
+
+
+`marionette.prefs.recommended`
+------------------------------
+
+By default Marionette attempts to set a range of preferences deemed
+suitable in automation when it starts.  These include the likes of
+disabling auto-updates, Telemetry, and first-run UX.
+
+The user preference file takes presedence over the recommended
+preferences, meaning any user-defined preference value will not be
+overridden.
+
+
+`marionette.contentListener`
+----------------------------
+
+Used internally in Marionette for determining whether content scripts
+can safely be reused.  Should not be tweaked manually.
+
+This preference is scheduled for removal.
--- a/testing/marionette/doc/index.rst
+++ b/testing/marionette/doc/index.rst
@@ -31,16 +31,17 @@ Marionette using the `protocol`_.
    Protocol.md
    Contributing.md
    Debugging.md
    Testing.md
    Taskcluster.md
    CodeStyle.md
    Patching.md
    SeleniumAtoms.md
+   Prefs.md
    internals/index
 
 See also:
 
 * Documentation for `Marionette Python client`_, which is used
   in-tree to write many kinds of Marionette-based tests.
 * Documentation for `Firefox Puppeteer`_, which is used to in-tree
   to write Firefox UI tests.