prefs module

Branch

class Branch(branch)
Arguments:
  • branch (string) – Preference subtree. Uses root tree given null.
Branch.get(pref, fallback)

Gets value of pref in its known type.

Arguments:
  • pref (string) – Preference name.
  • fallback
Throws:

TypeError – If pref is not a recognised preference and no fallback value has been provided.

Returns:

string|boolean|number – Value of pref, or the fallback value if pref does not exist.

Branch.set(pref, value)

Sets the value of pref.

Arguments:
  • pref (string) – Preference name.
  • value (string|boolean|number) – pref’s new value.
Throws:

TypeError – If value is not the correct type for pref.

EnvironmentPrefs

class EnvironmentPrefs()

Reads a JSON serialised blob stored in the environment.

EnvironmentPrefs.from(key)

Reads the environment variable key and tries to parse it as JSON Object, then provides an iterator over its keys and values.

If the environment variable is not set, this function returns empty.

Arguments:
  • key (string) – Environment variable.
Returns:

{Iterable.<string, (string|boolean|number)>

MarionetteBranch

class MarionetteBranch(branch)

Provides shortcuts for lazily getting and setting typed Marionette preferences.

Some of Marionette’s preferences are stored using primitive values that internally are represented by complex types. One such example is marionette.log.level which stores a string such as info or DEBUG, and which is represented as Log.Level.

Because we cannot trust the input of many of these preferences, this class provides abstraction that lets us safely deal with potentially malformed input. In the marionette.log.level example, DEBUG, Debug, and dEbUg are considered valid inputs and the LogBranch specialisation deserialises the string value to the correct Log.Level by sanitising the input data first.

A further complication is that we cannot rely on Preferences.jsm in Marionette. See https://bugzilla.mozilla.org/show_bug.cgi?id=1357517 for further details.

MarionetteBranch.clickToStart

The marionette.debugging.clicktostart preference delays server startup until a modal dialogue has been clicked to allow time for user to set breakpoints in the Browser Toolbox.

MarionetteBranch.contentListener

Whether content scripts can be safely reused.

MarionetteBranch.enabled

The marionette.enabled preference. When it returns true, this signifies that the Marionette server is running.

MarionetteBranch.logLevel

Fail-safe return of the current log level from preference marionette.log.level.

MarionetteBranch.port

The marionette.port preference, detailing which port the TCP server should listen on.

MarionetteBranch.recommendedPrefs

Gets the marionette.prefs.recommended preference, signifying whether recommended automation preferences will be set when Marionette is started.

MarionetteBranch.truncateLog

Certain log messages that are known to be long are truncated before they are dumped to stdout. The marionette.log.truncate preference indicates that the values should not be truncated.