From eb2244da5ae838e2844b549dddb395c820c61a6a Mon Sep 17 00:00:00 2001 From: Andreas Tolfsen Date: Sat, 14 Apr 2018 17:25:26 +0100 Subject: [PATCH] Bug 1432894 - Provide shorthands for Marionette prefs. r=whimboo This introduces a new testing/marionette/prefs.js module with shorthands for all of Marionette's preferences. Getters are provided for all preferences, but setters are only offered for preference we expect to mutate at runtime. The new module additionally provides a preference abstraction on top of nsIPrefService instead of Preferences.jsm. We cannot use Preferences.jsm during startup in Marionette because Marionette gets loaded unconditionally. Finally an EnvironmentPrefs class is provided for reading and iterating over preferences stored in JSON Objects in environment variables. MozReview-Commit-ID: FbgdBEkf5A --HG-- extra : rebase_source : 0d5b2f11dc94a74aff3f742ef191b72b159b5ee7 --- testing/marionette/doc/internals/prefs.rst | 17 ++ testing/marionette/jar.mn | 1 + testing/marionette/prefs.js | 245 +++++++++++++++++++++ testing/marionette/test/unit/test_prefs.js | 125 +++++++++++ testing/marionette/test/unit/xpcshell.ini | 3 +- 5 files changed, 389 insertions(+), 2 deletions(-) create mode 100644 testing/marionette/doc/internals/prefs.rst create mode 100644 testing/marionette/prefs.js create mode 100644 testing/marionette/test/unit/test_prefs.js diff --git a/testing/marionette/doc/internals/prefs.rst b/testing/marionette/doc/internals/prefs.rst new file mode 100644 index 000000000000..d54383b70f7e --- /dev/null +++ b/testing/marionette/doc/internals/prefs.rst @@ -0,0 +1,17 @@ +prefs module +============ + +Branch +------ +.. js:autoclass:: Branch + :members: + +EnvironmentPrefs +---------------- +.. js:autoclass:: EnvironmentPrefs + :members: + +MarionetteBranch +---------------- +.. js:autoclass:: MarionetteBranch + :members: diff --git a/testing/marionette/jar.mn b/testing/marionette/jar.mn index b69ff48eccfa..0debfb39adf0 100644 --- a/testing/marionette/jar.mn +++ b/testing/marionette/jar.mn @@ -36,6 +36,7 @@ marionette.jar: content/reftest.xul (reftest.xul) content/dom.js (dom.js) content/format.js (format.js) + content/prefs.js (prefs.js) #ifdef ENABLE_TESTS content/test.xul (chrome/test.xul) content/test2.xul (chrome/test2.xul) diff --git a/testing/marionette/prefs.js b/testing/marionette/prefs.js new file mode 100644 index 000000000000..ce790bd90388 --- /dev/null +++ b/testing/marionette/prefs.js @@ -0,0 +1,245 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this file, + * You can obtain one at http://mozilla.org/MPL/2.0/. */ + +"use strict"; + +ChromeUtils.import("resource://gre/modules/Log.jsm"); +ChromeUtils.import("resource://gre/modules/Services.jsm"); +ChromeUtils.import("resource://gre/modules/XPCOMUtils.jsm"); + +XPCOMUtils.defineLazyServiceGetter(this, "env", + "@mozilla.org/process/environment;1", + "nsIEnvironment"); + +const { + PREF_BOOL, + PREF_COMPLEX, + PREF_INT, + PREF_INVALID, + PREF_STRING, +} = Ci.nsIPrefBranch; + +this.EXPORTED_SYMBOLS = [ + "Branch", + "MarionettePrefs", +]; + +class Branch { + /** + * @param {string=} branch + * Preference subtree. Uses root tree given `null`. + */ + constructor(branch) { + this._branch = Services.prefs.getBranch(branch); + } + + /** + * Gets value of `pref` in its known type. + * + * @param {string} pref + * Preference name. + * @param {?=} fallback + * Fallback value to return if `pref` does not exist. + * + * @return {(string|boolean|number)} + * Value of `pref`, or the `fallback` value if `pref` does + * not exist. + * + * @throws {TypeError} + * If `pref` is not a recognised preference and no `fallback` + * value has been provided. + */ + get(pref, fallback = null) { + switch (this._branch.getPrefType(pref)) { + case PREF_STRING: + return this._branch.getStringPref(pref); + + case PREF_BOOL: + return this._branch.getBoolPref(pref); + + case PREF_INT: + return this._branch.getIntPref(pref); + + case PREF_COMPLEX: + throw new TypeError(`Unsupported complex preference: ${pref}`); + + case PREF_INVALID: + default: + if (fallback != null) { + return fallback; + } + throw new TypeError(`Unrecognised preference: ${pref}`); + } + } + + /** + * Sets the value of `pref`. + * + * @param {string} pref + * Preference name. + * @param {(string|boolean|number)} value + * `pref`'s new value. + * + * @throws {TypeError} + * If `value` is not the correct type for `pref`. + */ + set(pref, value) { + let typ; + if (typeof value != "undefined" && value != null) { + typ = value.constructor.name; + } + + switch (typ) { + case "String": + // Unicode compliant + return this._branch.setStringPref(pref, value); + + case "Boolean": + return this._branch.setBoolPref(pref, value); + + case "Number": + return this._branch.setIntPref(pref, value); + + default: + throw new TypeError(`Illegal preference type value: ${typ}`); + } + } +} + +/** + * 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. + * + * Usage:: + * + * ChromeUtils.import("resource://gre/modules/Log.jsm"); + * const {MarionettePrefs} = ChromeUtils.import("chrome://marionette/content/prefs.js", {}); + * + * const log = Log.repository.getLogger("Marionette"); + * log.level = MarionettePrefs.log.level; + */ +class MarionetteBranch extends Branch { + constructor(branch = "marionette.") { + super(branch); + } + + /** + * The `marionette.enabled` preference. When it returns true, + * this signifies that the Marionette server is running. + * + * @return {boolean} + */ + get enabled() { + return this.get("enabled", false); + } + + set enabled(isEnabled) { + this.set("enabled", isEnabled); + } + + /** + * The `marionette.port` preference, detailing which port + * the TCP server should listen on. + * + * @return {number} + */ + get port() { + return this.get("port", 2828); + } + + set port(newPort) { + this.set("port", newPort); + } + + /** + * Fail-safe return of the current log level from preference + * `marionette.log.level`. + * + * @return {Log.Level} + */ + get logLevel() { + switch (this.get("log.level", "info").toLowerCase()) { + case "fatal": + return Log.Level.Fatal; + case "error": + return Log.Level.Error; + case "warn": + return Log.Level.Warn; + case "config": + return Log.Level.Config; + case "debug": + return Log.Level.Debug; + case "trace": + return Log.Level.Trace; + case "info": + default: + return Log.Level.Info; + } + } + + /** + * Gets the `marionette.prefs.recommended` preference, signifying + * whether recommended automation preferences will be set when + * Marionette is started. + * + * @return {boolean} + */ + get recommendedPrefs() { + return this.get("prefs.recommended", true); + } +} + +/** Reads a JSON serialised blob stored in the environment. */ +class EnvironmentPrefs { + /** + * 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. + * + * @param {string} key + * Environment variable. + * + * @return {Iterable. + */ + static* from(key) { + if (!env.exists(key)) { + return; + } + + let prefs; + try { + prefs = JSON.parse(env.get(key)); + } catch (e) { + throw new TypeError(`Unable to parse prefs from ${key}`, e); + } + + for (let prefName of Object.keys(prefs)) { + yield [prefName, prefs[prefName]]; + } + } +} + +this.Branch = Branch; +this.EnvironmentPrefs = EnvironmentPrefs; + +// There is a future potential of exposing this as Marionette.prefs.port +// if we introduce a Marionette.jsm module. +this.MarionettePrefs = new MarionetteBranch(); diff --git a/testing/marionette/test/unit/test_prefs.js b/testing/marionette/test/unit/test_prefs.js new file mode 100644 index 000000000000..c8544932d321 --- /dev/null +++ b/testing/marionette/test/unit/test_prefs.js @@ -0,0 +1,125 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this file, + * You can obtain one at http://mozilla.org/MPL/2.0/. */ + +"use strict"; + +ChromeUtils.import("resource://gre/modules/Log.jsm"); +ChromeUtils.import("resource://gre/modules/Services.jsm"); +ChromeUtils.import("resource://gre/modules/XPCOMUtils.jsm"); + +XPCOMUtils.defineLazyServiceGetter( + this, "env", "@mozilla.org/process/environment;1", "nsIEnvironment"); + +const { + Branch, + EnvironmentPrefs, + MarionettePrefs, +} = ChromeUtils.import("chrome://marionette/content/prefs.js", {}); + +function reset() { + Services.prefs.setBoolPref("test.bool", false); + Services.prefs.setStringPref("test.string", "foo"); + Services.prefs.setIntPref("test.int", 777); +} + +// Give us something to work with: +reset(); + +add_test(function test_Branch_get_root() { + let root = new Branch(null); + equal(false, root.get("test.bool")); + equal("foo", root.get("test.string")); + equal(777, root.get("test.int")); + Assert.throws(() => root.get("doesnotexist"), /TypeError/); + + run_next_test(); +}); + +add_test(function test_Branch_get_branch() { + let test = new Branch("test."); + equal(false, test.get("bool")); + equal("foo", test.get("string")); + equal(777, test.get("int")); + Assert.throws(() => test.get("doesnotexist"), /TypeError/); + + run_next_test(); +}); + +add_test(function test_Branch_set_root() { + let root = new Branch(null); + + try { + root.set("test.string", "bar"); + root.set("test.in", 777); + root.set("test.bool", true); + + equal("bar", Services.prefs.getStringPref("test.string")); + equal(777, Services.prefs.getIntPref("test.int")); + equal(true, Services.prefs.getBoolPref("test.bool")); + } finally { + reset(); + } + + run_next_test(); +}); + +add_test(function test_Branch_set_branch() { + let test = new Branch("test."); + + try { + test.set("string", "bar"); + test.set("int", 888); + test.set("bool", true); + + equal("bar", Services.prefs.getStringPref("test.string")); + equal(888, Services.prefs.getIntPref("test.int")); + equal(true, Services.prefs.getBoolPref("test.bool")); + } finally { + reset(); + } + + run_next_test(); +}); + +add_test(function test_EnvironmentPrefs_from() { + let prefsTable = { + "test.bool": true, + "test.int": 888, + "test.string": "bar", + }; + env.set("FOO", JSON.stringify(prefsTable)); + + try { + for (let [key, value] of EnvironmentPrefs.from("FOO")) { + equal(prefsTable[key], value); + } + } finally { + env.set("FOO", null); + } + + run_next_test(); +}); + +add_test(function test_MarionettePrefs_getters() { + equal(false, MarionettePrefs.enabled); + equal(2828, MarionettePrefs.port); + equal(Log.Level.Info, MarionettePrefs.logLevel); + equal(true, MarionettePrefs.recommendedPrefs); + + run_next_test(); +}); + +add_test(function test_MarionettePrefs_setters() { + try { + MarionettePrefs.enabled = true; + MarionettePrefs.port = 777; + equal(true, MarionettePrefs.enabled); + equal(777, MarionettePrefs.port); + } finally { + Services.prefs.clearUserPref("marionette.enabled"); + Services.prefs.clearUserPref("marionette.port"); + } + + run_next_test(); +}); diff --git a/testing/marionette/test/unit/xpcshell.ini b/testing/marionette/test/unit/xpcshell.ini index 9121191d9469..016e9bae44c1 100644 --- a/testing/marionette/test/unit/xpcshell.ini +++ b/testing/marionette/test/unit/xpcshell.ini @@ -2,8 +2,6 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at http://mozilla.org/MPL/2.0/. -# xpcshell unit tests for Marionette - [DEFAULT] skip-if = appname == "thunderbird" @@ -18,5 +16,6 @@ skip-if = appname == "thunderbird" [test_format.js] [test_message.js] [test_navigate.js] +[test_prefs.js] [test_session.js] [test_sync.js]